minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,220 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/ralphLoop.e2e.test.ts
+ * ------------------------------------------------------------
+ *  ralph-loop.yaml 端到端（真实 yaml 文件 + 脚本化 DI chat，零网络）。
+ *
+ *  背景：重写前的 ralph-loop 有 5 处独立缺陷且 while/fresh_context 零测试覆盖
+ *  （从未被端到端跑通过）：max_iterations 模板不插值→静默 0 次迭代、裸 ${goal}
+ *  插空、${phase.toUpperCase()} 必抛错、llm 步当赋值用、哨兵 includes 误判
+ *  （learning-only 输出直接终止循环 / "incomplete" 含 "complete" 误判完成 /
+ *  auto_advance 吞掉 replan）。本文件以「学习一轮 → 完成一轮」的剧本钉死全链路。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } 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 type { LoopEvent, Message, Provider } from '../../../src/types.js';
+import { parseWorkflowFile } from '../src/loader.js';
+import { runWorkflow } from '../src/runner.js';
+import type { RunContext, WorkflowEvent } from '../src/types.js';
+
+type WfOrLoop = WorkflowEvent | LoopEvent;
+
+const YAML_PATH = join(import.meta.dir, '..', '..', '..', 'workflows', 'ralph-loop.yaml');
+
+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('ralph-loop.yaml 端到端（while + fresh_context + 哨兵协议）', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-ralph-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    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('学习一轮 → 完成一轮：恰 2 次迭代 break、教训存档不重复、目标/阶段/教训进 prompt', async () => {
+    const def = await parseWorkflowFile(YAML_PATH); // 真实 yaml 必须能加载
+    def.self_heal = { ...def.self_heal, retry_delay_ms: 0 }; // 测试不等退避
+
+    // 脚本化 chat（按调用顺序）——教训提取已是确定性 set（extract/join 内置函数），
+    // 不再占一次 LLM 调用：
+    //  #1 work(iter0)  → learning-only 输出（无 promise 哨兵——不得终止循环！）
+    //  #2 work(iter1)  → 完成哨兵
+    //  #3 final_summary
+    // ⚠️ messages 是 runQuery 原地 mutate 的共享 history 引用，必须在调用时快照成文本
+    const calls: string[] = [];
+    let n = 0;
+    ctx.chat = async function* (args: { messages: Message[] }) {
+      calls.push(args.messages.map((m) => String(m.content ?? '')).join('\n'));
+      n++;
+      const reply =
+        n === 1
+          ? '我做了规划，发现 <learning>边界条件要先写测试</learning>，下一轮开始实现。'
+          : n === 2
+            ? '已全部实现并自测通过。<promise>DONE</promise>'
+            : '总结：目标完成。';
+      yield { type: 'text_delta', delta: reply };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const events = await collect(
+      runWorkflow(def, { goal: '实现登录模块', max_iterations: 5, verify_checks: '' }, ctx),
+    );
+
+    // 整链成功
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(
+      events.some((e) => e.type === 'error' && e.error.includes('Workflow halted')),
+    ).toBe(false);
+
+    // 恰 2 次迭代后 break（R1 回归锚：max_iterations 模板曾静默 0 次迭代）
+    const loopEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'main_loop',
+    );
+    expect(loopEnd?.output).toContain('2 iterations');
+    expect(loopEnd?.output).toContain('break');
+
+    // chat 恰 3 次（多了说明循环失控/少了说明被误终止；教训提取零 LLM）
+    expect(n).toBe(3);
+
+    // iter0 的 work prompt：目标原文（R2 锚）、阶段 PLAN 大写（R3 锚）、哨兵协议
+    const p0 = calls[0];
+    expect(p0).toContain('实现登录模块');
+    expect(p0).toContain('当前阶段: PLAN');
+    expect(p0).toContain('<promise>DONE</promise>');
+
+    // iter1 的 work prompt：auto_advance 推进到 BUILD（learning 不是流程哨兵，不阻止推进），
+    // 且上一轮教训进了「关键教训」节
+    const p2 = calls[1];
+    expect(p2).toContain('当前阶段: BUILD');
+    expect(p2).toContain('关键教训');
+    expect(p2).toContain('边界条件要先写测试');
+    // fresh_context：iter1 的消息里不应携带 iter0 的对话产物
+    expect(p2).not.toContain('我做了规划');
+
+    // 教训档案恰好一条、不重复（iter1 无 learning 标签时 extract → '' 不得重复累积）
+    // 注意成功后状态目录被归档为 ralph-loop.done
+    const learningsPath = join(
+      tmp,
+      '.minimal-agent-workflow',
+      'ralph-loop.done',
+      'learnings.md',
+    );
+    expect(existsSync(learningsPath)).toBe(true);
+    const learnings = readFileSync(learningsPath, 'utf8');
+    expect(learnings).toContain('边界条件要先写测试');
+    expect(learnings.match(/边界条件要先写测试/g)?.length).toBe(1);
+  });
+
+  it('R5 锚：输出含 "incomplete" 等普通词 + learning 标签 → 不被误判完成/不误终止', async () => {
+    const def = await parseWorkflowFile(YAML_PATH);
+    def.self_heal = { ...def.self_heal, retry_delay_ms: 0 };
+
+    // iter0: 含 "incomplete"（曾因 includes(complete) 误判 DONE）+ learning（提取零 LLM）；
+    // iter1: NEED_REPLAN（auto_advance 有 <promise> 守卫，phase 应回 PLAN 且不被推进吞掉）；
+    // iter2: 真 DONE。
+    let n = 0;
+    ctx.chat = async function* () {
+      n++;
+      const reply =
+        n === 1
+          ? 'work is incomplete, still analyzing. <learning>先列验收标准</learning>'
+          : n === 2
+            ? '这个方案走不通。<promise>NEED_REPLAN</promise>'
+            : n === 3
+              ? '换方案后完成。<promise>DONE</promise>'
+              : '总结。';
+      yield { type: 'text_delta', delta: reply };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const events = await collect(
+      runWorkflow(def, { goal: 'G', max_iterations: 6, verify_checks: '' }, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const loopEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'main_loop',
+    );
+    // 3 轮迭代（incomplete 轮没有被误判完成、NEED_REPLAN 轮没有终止循环）
+    expect(loopEnd?.output).toContain('3 iterations');
+    expect(loopEnd?.output).toContain('break');
+  });
+
+  it('验证门：DONE 哨兵但 verify 失败 → 不 break、回 BUILD 继续（模型谎报拦截）', async () => {
+    const def = await parseWorkflowFile(YAML_PATH);
+    def.self_heal = { ...def.self_heal, retry_delay_ms: 0 };
+
+    let n = 0;
+    ctx.chat = async function* () {
+      n++;
+      const reply =
+        n === 1
+          ? '我说完成了。<promise>DONE</promise>' // 谎报：验证门会拦
+          : n === 2
+            ? '这次真完成了。<promise>DONE</promise>'
+            : '总结。';
+      yield { type: 'text_delta', delta: reply };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const events = await collect(
+      runWorkflow(
+        def,
+        {
+          goal: 'G',
+          // verify 永远失败（文件不存在）+ 上限 2 轮：两轮谎报 DONE 都被验证门
+          // 拦下回 BUILD（不 break），最终以「达到上限」退出而非误判完成。
+          max_iterations: 2,
+          verify_checks: 'file_exists:./definitely-not-exists.txt',
+        },
+        ctx,
+      ),
+    );
+
+    // 两轮都谎报 DONE 但验证门都拦下 → 不 break，达上限退出
+    const loopEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'main_loop',
+    );
+    expect(loopEnd?.output).toContain('达到上限');
+    // 工作流本身正常收尾（验证门拦截不是 halt）
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+});

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

@@ -0,0 +1,265 @@
+/**
+ * ============================================================
+ *  test/workflows/recovery.test.ts —— onError:'recover' 自适应恢复
+ * ------------------------------------------------------------
+ *  验证「确定性工作流 × 随机应变 agent」的结合点：
+ *    - 动作 step 失败 + onError:'recover' → 起恢复 agent（miniReAct）救回
+ *      → 用同一 capture 绑定结果 → workflow 继续到 done
+ *    - 恢复也失败 → honest halt（error + 无 done）
+ *    - onError 默认(halt) → 不触发恢复（recover 是 opt-in，老行为不变）
+ *
+ *  策略（同 runner.test.ts）：
+ *    - 失败触发器：未知工具 NoSuchTool9999（execToolStep 直接 throw）
+ *    - 恢复路径最终经 runRecovery → miniReAct → chat，mock client.js 控制其输出
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import type { LoopEvent, Provider } from '../../../src/types.js';
+import { runWorkflow } from '../src/runner.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/recovery (onError:recover)', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-recover-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: [] };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('tool 失败 → 恢复 agent 救回 → workflow 继续到 done + capture 绑定', async () => {
+    // 恢复 agent 的 LLM：无 tool_calls，直接给出最终文本 'fixed-it'
+    mock.module('../../../src/llm/client.js', () => ({
+      chat: async function* () {
+        yield { type: 'text_delta', delta: 'fixed-' };
+        yield { type: 'text_delta', delta: 'it' };
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'recover-ok',
+      description: '让一个失败的步骤被恢复 agent 救回',
+      steps: [
+        {
+          id: 's1',
+          tool: 'NoSuchTool9999',
+          onError: 'recover',
+          capture: { content: 'msg' },
+        },
+        // capture 绑定成功（msg='fixed-it'）则此 assert 通过
+        { id: 'check', type: 'assert', condition: 'msg == "fixed-it"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    // 恢复成功 → 工作流跑完
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 全程无致命 error（恢复吸收了失败 + check 通过）
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    // 恢复前响亮告知：一条 warning 说明在自适应恢复
+    const warn = events.find(
+      (e): e is { type: 'warning'; message: string } => e.type === 'warning',
+    );
+    expect(warn).toBeDefined();
+    expect(warn!.message).toContain('自适应恢复');
+    // s1 的 step_end 是 ok:true 且 output 标注 recovered
+    const s1End = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 's1',
+    );
+    expect(s1End?.ok).toBe(true);
+    expect(s1End?.output).toContain('recovered');
+  });
+
+  it('恢复也失败 → honest halt（error + 无 done，后续步骤不跑）', async () => {
+    // 恢复 agent 的 LLM 直接抛错 → miniReAct 抛 → runRecovery 返回 null → halt
+    mock.module('../../../src/llm/client.js', () => ({
+      chat: async function* () {
+        throw new Error('llm 暂时不可用');
+        // eslint-disable-next-line no-unreachable
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'recover-fail',
+      description: '恢复也救不回',
+      steps: [
+        { id: 's1', tool: 'NoSuchTool9999', onError: 'recover' },
+        { id: 'after', 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);
+    // 尝试过恢复（有 warning）
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('自适应恢复')),
+    ).toBe(true);
+    // 恢复失败后 halt，后续步骤 after 从未 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).not.toContain('after');
+  });
+
+  it('onError 默认(halt) → 不触发恢复（recover 是 opt-in，老行为不变）', async () => {
+    const def: WorkflowDef = {
+      name: 'default-halt',
+      description: '默认 halt 不应起恢复',
+      steps: [
+        { id: 's1', tool: 'NoSuchTool9999' }, // 无 onError
+        { id: 'after', 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);
+    // 关键：没有任何「自适应恢复」warning → 证明恢复未被触发
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('自适应恢复')),
+    ).toBe(false);
+  });
+
+  it('恢复 agent 显式放弃（__RECOVERY_GIVEUP__）→ honest halt 且错误带原因', async () => {
+    // 恢复 agent 没真做成、按约定输出唯一放弃标记 + 原因
+    mock.module('../../../src/llm/client.js', () => ({
+      chat: async function* () {
+        yield {
+          type: 'text_delta',
+          delta: '__AGENT_GIVEUP__: 端口被占且无法更换',
+        };
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'recover-giveup',
+      description: '恢复 agent 诚实放弃',
+      steps: [
+        {
+          id: 's1',
+          tool: 'NoSuchTool9999',
+          onError: 'recover',
+          capture: { content: 'msg' },
+        },
+        { id: 'after', type: 'assert', condition: 'true' }, // 不应执行
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    // 显式放弃 → halt（不绑脏值、不继续）
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    const err = events.find(
+      (e): e is { type: 'error'; error: string } => e.type === 'error',
+    );
+    expect(err).toBeDefined();
+    // 放弃原因透传进 halt 文案，且标注是自适应恢复未成功
+    expect(err!.error).toContain('端口被占');
+    expect(err!.error).toContain('自适应恢复未成功');
+    // 确实尝试过恢复
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('自适应恢复')),
+    ).toBe(true);
+    // s1 落 ok:false；after 从未 start
+    const s1End = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 's1',
+    );
+    expect(s1End?.ok).toBe(false);
+    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('恢复 agent 产出为空 → 不绑脏值、honest halt（禁伪造闸门）', async () => {
+    // 既不调工具、也不给任何文本 → 空产出。验证闸门必须拦下，不能当「救回」。
+    mock.module('../../../src/llm/client.js', () => ({
+      chat: async function* () {
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'recover-empty',
+      description: '空产出不该被当成救回',
+      steps: [
+        {
+          id: 's1',
+          tool: 'NoSuchTool9999',
+          onError: 'recover',
+          capture: { content: 'msg' },
+        },
+        { id: 'after', type: 'assert', condition: 'true' }, // 不应执行
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    const err = events.find(
+      (e): e is { type: 'error'; error: string } => e.type === 'error',
+    );
+    expect(err).toBeDefined();
+    expect(err!.error).toContain('没有产出');
+    // s1 ok:false；空串没有被绑进 msg 后继续（after 从未 start）
+    const s1End = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 's1',
+    );
+    expect(s1End?.ok).toBe(false);
+    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');
+  });
+});