minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,270 @@
+/**
+ * ============================================================
+ *  test/taskLifecycle.test.ts —— 任务身份生命周期 + in-run retry 的新增覆盖
+ * ------------------------------------------------------------
+ *  钉死本轮修复的三条新行为（此前缺直接覆盖）：
+ *    L2  completed 经 .done 检测：成功归档后，同 goal 重跑 → completed（报真实产物），
+ *        不再因 archive 改名而误判 fresh 重跑。
+ *    L3  new-task 清声明产物：换一个不同 goal 重跑同名 workflow → new-task，
+ *        删掉旧任务在 cwd 留下的声明产物（如旧 PLAN.md），不污染新任务。
+ *    retry  in-run 重试：llm 步首次 LLM 出错（空产出）→ 抛异常 → runner 按 max_retries
+ *        确定性重跑同一步 → 第 2 次成功 → workflow_done（验证 P0-1 + 重试闭环）。
+ *
+ *  L2/L3 用 WorkflowState 单元测试（无需 LLM）；retry 用 runWorkflow + ctx.chat DI。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { WorkflowState } from '../src/workflowState.js';
+import { runWorkflow } from '../src/runner.js';
+import type { LoopEvent, Provider } from '../../../src/types.js';
+import type { RunContext, StepDef, 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;
+}
+
+const STEPS: StepDef[] = [{ id: 's1', type: 'assert', condition: 'true' }];
+
+describe('任务身份生命周期（L2 completed / L3 new-task 清产物）', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-lifecycle-'));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('成功归档后同 goal 重跑 → completed，报真实存在的声明产物（L2）', async () => {
+    const artifacts = ['PLAN.md'];
+
+    // 第一次：fresh
+    const s1 = new WorkflowState(tmp, 'plan');
+    const r1 = await s1.init('plan', { goal: '目标A' }, STEPS, 1, artifacts);
+    expect(r1.mode).toBe('fresh');
+
+    // 模拟成功：产物落到 cwd 根 + 标记 done + 归档（改名 .done）
+    writeFileSync(join(tmp, 'PLAN.md'), '# plan');
+    await s1.markDone();
+    await s1.archive();
+    // 归档后活动目录已改名 .done（E6 后按名隔离）
+    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'plan'))).toBe(false);
+    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'plan.done'))).toBe(true);
+
+    // 第二次：同 goal 重跑 → completed（经 .done 检测），报真实产物
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '目标A' }, STEPS, 1, artifacts);
+    expect(r2.mode).toBe('completed');
+    expect(r2.artifacts).toEqual(['PLAN.md']);
+  });
+
+  it('completed 只报实际存在的产物（声明了但被删的不报）', async () => {
+    const s1 = new WorkflowState(tmp, 'plan');
+    await s1.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md', 'EXTRA.md']);
+    writeFileSync(join(tmp, 'PLAN.md'), '# plan'); // 只写 PLAN.md，不写 EXTRA.md
+    await s1.markDone();
+    await s1.archive();
+
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md', 'EXTRA.md']);
+    expect(r2.mode).toBe('completed');
+    expect(r2.artifacts).toEqual(['PLAN.md']); // EXTRA.md 不存在 → 不报
+  });
+
+  it('换不同 goal 重跑同名 workflow → new-task，清掉旧任务的声明产物（L3）', async () => {
+    // 任务A 成功归档，留下 PLAN.md
+    const s1 = new WorkflowState(tmp, 'plan');
+    await s1.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md']);
+    writeFileSync(join(tmp, 'PLAN.md'), '# plan A');
+    await s1.markDone();
+    await s1.archive();
+    expect(existsSync(join(tmp, 'PLAN.md'))).toBe(true);
+
+    // 换完全不同的 goal 重跑 → new-task，旧 PLAN.md 被清（不污染新任务）
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '完全不相关的目标B' }, STEPS, 1, ['PLAN.md']);
+    expect(r2.mode).toBe('new-task');
+    expect(r2.cleanedArtifacts).toContain('PLAN.md');
+    expect(existsSync(join(tmp, 'PLAN.md'))).toBe(false);
+  });
+
+  it('legacy 状态文件（无 artifacts 字段）+ 同名 workflow 换 goal → new-task 用本次声明清单兜底清理', async () => {
+    // 手写旧版 current.json（没有 artifacts 字段）+ 磁盘残留 PLAN.md（E6 后按名隔离路径）
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(tmp, '.minimal-agent-workflow', 'plan'), { recursive: true });
+    writeFileSync(
+      join(tmp, '.minimal-agent-workflow', 'plan', 'current.json'),
+      JSON.stringify({
+        name: 'plan',
+        taskId: 'deadbeefdeadbeef',
+        status: 'running',
+        startedAt: '2026-01-01T00:00:00.000Z',
+        // 注意：无 artifacts 字段（legacy）
+      }),
+    );
+    writeFileSync(join(tmp, 'PLAN.md'), '# 旧任务残留');
+
+    const s = new WorkflowState(tmp, 'plan');
+    const r = await s.init('plan', { goal: '全新目标' }, STEPS, 1, ['PLAN.md']);
+    expect(r.mode).toBe('new-task');
+    // 兜底清理生效：同名 workflow 的声明产物语义稳定，按本次声明清单清掉残留
+    expect(r.cleanedArtifacts).toContain('PLAN.md');
+    expect(existsSync(join(tmp, 'PLAN.md'))).toBe(false);
+  });
+
+  it('/new 后孤儿产物：无任何状态但声明产物已存在 → fresh 启动时清理（全新任务从干净状态开始）', async () => {
+    // /new 删掉了 .minimal-agent-workflow*/（artifacts 清单随之丢失），PLAN.md 成孤儿。
+    // 用户约定：全新 plan 一律清理残留与中间文件；删除范围仅限本工作流声明的产物。
+    writeFileSync(join(tmp, 'PLAN.md'), '# 孤儿产物');
+
+    const s = new WorkflowState(tmp, 'plan');
+    const r = await s.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md']);
+    expect(r.mode).toBe('fresh');
+    expect(existsSync(join(tmp, 'PLAN.md'))).toBe(false);
+    // 可见化：runner 据此报「已清理旧产物」warning
+    expect(r.cleanedArtifacts).toEqual(['PLAN.md']);
+  });
+
+  it('resume 恢复点用最后完成步的【索引】而非 checkpoint 计数（when 跳过步不再被重复执行）', async () => {
+    // steps: s1 ✓ / s2(when=false 跳过，无 checkpoint) / s3 ✓ / s4 失败。
+    // 计数法：2 个 checkpoint - backoff(1) = 1 → 从 s2 重跑（重复执行已決策跳过的步）；
+    // 索引法：s3 的索引 2 + 1 - 1 = 2 → 从 s3 重跑（正确的覆盖重合区）。
+    const stepsWithSkip: StepDef[] = [
+      { id: 's1', type: 'assert', condition: 'true' },
+      { id: 's2', type: 'assert', condition: 'true', when: 'false' },
+      { id: 's3', type: 'assert', condition: 'true' },
+      { id: 's4', type: 'assert', condition: 'true' },
+    ];
+    const s1 = new WorkflowState(tmp, 'plan');
+    await s1.init('plan', { goal: '目标A' }, stepsWithSkip, 1, []);
+    await s1.recordCheckpoint('s1', 'ok', {}, {});
+    await s1.recordCheckpoint('s3', 'ok', {}, {});
+    // 不 markDone（s4 失败现场）
+
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r = await s2.init('plan', { goal: '目标A' }, stepsWithSkip, 1, []);
+    expect(r.mode).toBe('resume');
+    expect(r.startFrom).toBe(2); // s3 的索引，而不是计数法的 1
+  });
+
+  it('同任务 resume 不清理声明产物（清理只发生在 fresh/new-task）', async () => {
+    const s1 = new WorkflowState(tmp, 'plan');
+    await s1.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md']);
+    writeFileSync(join(tmp, 'PLAN.md'), '# 半成品'); // 任务自己写出的中间产物
+    // 不 markDone（模拟中断）→ 同 goal 重跑 resume
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '目标A' }, STEPS, 1, ['PLAN.md']);
+    expect(r2.mode).toBe('resume');
+    expect(existsSync(join(tmp, 'PLAN.md'))).toBe(true); // 现场保留
+  });
+
+  it('未完成（中断）任务同 goal 重跑 → resume（非 completed）', async () => {
+    const s1 = new WorkflowState(tmp, 'plan');
+    const r1 = await s1.init('plan', { goal: '目标A' }, STEPS, 1, []);
+    expect(r1.mode).toBe('fresh');
+    // 不 markDone、不 archive（模拟中断）
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '目标A' }, STEPS, 1, []);
+    expect(r2.mode).toBe('resume');
+  });
+});
+
+describe('in-run retry（self_heal / max_retries）', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-retry-'));
+    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('llm 步首次 LLM 出错（空产出）→ max_retries 重跑 → 第 2 次成功 → done', async () => {
+    let calls = 0;
+    // 第 1 次 chat 抛错 → 真实 runQuery 捕获为 llm_error → llm.ts 空产出抛异常 → runner 重试；
+    // 第 2 次 chat 正常产出 → 成功。
+    ctx.chat = async function* () {
+      calls++;
+      if (calls === 1) throw new Error('transient LLM error');
+      yield { type: 'text_delta', delta: 'recovered-output' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'retry-wf',
+      description: 'd',
+      steps: [
+        { id: 'g', llm: 'do it', capture: { text: 'out' }, max_retries: 1 },
+        { id: 'check', type: 'assert', condition: 'out == "recovered-output"' },
+      ],
+    };
+
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    // 确实重试了：chat 被调 2 次 + 有一条重试 warning
+    expect(calls).toBe(2);
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('重试')),
+    ).toBe(true);
+  });
+
+  it('max_retries 用尽仍失败 → halt（无 done）', async () => {
+    // chat 每次都抛 → llm 步每次空产出抛异常 → 重试用尽 → 默认 onError=halt。
+    ctx.chat = async function* () {
+      throw new Error('always fails');
+      // biome-ignore lint/correctness/noUnreachable: stub
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'retry-exhaust',
+      description: 'd',
+      steps: [
+        { id: 'g', llm: 'do it', max_retries: 1 },
+        { id: 'after', 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')).toBe(true);
+    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');
+  });
+});

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

@@ -0,0 +1,221 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/toolArtifactOverwrite.test.ts
+ * ------------------------------------------------------------
+ *  tool 步「声明产物覆盖」契约（P0-B 回归锚）：
+ *
+ *  内核 Write/Edit 有「文件已存在必须先 Read」守卫（fileState 进程级 Map，
+ *  跨进程 / resume / 残留旧产物时必空）。确定性 tool 步（如 plan.yaml 的
+ *  write_plan: tool:Write → ./PLAN.md）的 args 是 yaml 写死的，模型没机会先
+ *  Read —— 曾导致旧 PLAN.md 存在时整条工作流 halt（且重试同败）。
+ *
+ *  契约：目标文件命中**声明产物**（def 级 / step 级 artifacts:）→ 自动
+ *  pre-Read 解守卫、覆盖成功；非声明产物 → 盲写保护原样生效。
+ *  每个用例 clearFileState() 模拟新进程（守卫状态为空的最坏情形）。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import {
+  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 { clearFileState } from '../../../src/tools/shared/fileState.js';
+import { ALL_TOOLS } from '../../../src/tools/index.js';
+import type { LoopEvent, Provider } from '../../../src/types.js';
+import { computeTaskId } from '../src/taskIdentity.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/tool 步声明产物覆盖（P0-B）', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-artifact-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+    clearFileState(); // 模拟新进程：守卫的"已 Read"记录为空
+    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: ALL_TOOLS };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    clearFileState();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function writeDef(artifacts: {
+    defLevel?: string[];
+    stepLevel?: string[];
+    filePath?: string;
+  }): WorkflowDef {
+    return {
+      name: 'write-out',
+      description: '确定性落盘',
+      artifacts: artifacts.defLevel,
+      steps: [
+        {
+          id: 'w1',
+          tool: 'Write',
+          args: {
+            file_path: artifacts.filePath ?? 'OUT.md',
+            content: 'fresh-content',
+          },
+          artifacts: artifacts.stepLevel,
+        },
+      ],
+    };
+  }
+
+  /** 预置「同任务未完成」状态：让下一次 runWorkflow 判 resume（不清产物、不重建），
+   *  从而专测 tool 步的声明产物 pre-Read 解守卫路径（fresh/new-task 会先把残留清掉，
+   *  到不了守卫；resume + 新进程才是守卫挡死的真实场景）。 */
+  function seedSameTaskState(name: string): void {
+    const { hash } = computeTaskId(name, {});
+    // E6 后状态目录按 workflow 名隔离
+    const dir = join(tmp, '.minimal-agent-workflow', name);
+    mkdirSync(join(dir, 'checkpoints'), { recursive: true });
+    writeFileSync(
+      join(dir, 'current.json'),
+      JSON.stringify({
+        name,
+        taskId: hash,
+        status: 'running',
+        startedAt: '2026-01-01T00:00:00.000Z',
+      }),
+    );
+  }
+
+  it('残留旧产物 + def 级 artifacts 声明 → fresh 启动时清理 + warning + 正常写出', async () => {
+    // 复现现场：上次任务残留的 0 字节产物（如 /new 后的孤儿 PLAN.md）。
+    // 全新任务约定：启动即清理声明产物残留，从干净状态开始。
+    writeFileSync(join(tmp, 'OUT.md'), '');
+
+    const events = await collect(
+      runWorkflow(writeDef({ defLevel: ['OUT.md'] }), {}, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+    // 清理可见化：fresh 启动时报「已清理旧产物」warning
+    expect(
+      events.some((e) => e.type === 'warning' && e.message.includes('旧产物')),
+    ).toBe(true);
+  });
+
+  it('同任务 resume（新进程）+ def 级声明 → pre-Read 解守卫、覆盖自家产物成功', async () => {
+    // resume 不清产物（现场保留），新进程守卫表为空 → 必须靠 pre-Read 解守卫
+    seedSameTaskState('write-out');
+    writeFileSync(join(tmp, 'OUT.md'), '# 上次任务自己写出的半成品');
+
+    const events = await collect(
+      runWorkflow(writeDef({ defLevel: ['OUT.md'] }), {}, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+  });
+
+  it('残留同名文件但【未】声明 artifact → 盲写保护原样生效（halt 带"请先 Read"）', async () => {
+    writeFileSync(join(tmp, 'OUT.md'), '用户自己的文件，不该被盲写');
+
+    const events = await collect(runWorkflow(writeDef({}), {}, 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('Read');
+    // 内容未被覆盖
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toContain('用户自己的文件');
+  });
+
+  it('resume + 仅 step 级 artifacts 声明也走 pre-Read', async () => {
+    seedSameTaskState('write-out');
+    writeFileSync(join(tmp, 'OUT.md'), 'old');
+
+    const events = await collect(
+      runWorkflow(writeDef({ stepLevel: ['OUT.md'] }), {}, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+  });
+
+  it('resume + 声明产物超字符上限（真 Read 会截断）→ 解截断守卫、覆盖成功', async () => {
+    // 复现 plan.yaml 回写「变长 PLAN.md」的 halt（真实事故）：声明产物已存在且
+    // 内容 > DEFAULT_MAX_RESULT_SIZE_CHARS(30000) —— 旧实现 pre-Read 用真 Read 解守卫，
+    // 会触发字符上限截断 → 记 truncated:true → Write 的「截断禁写」硬守卫拒绝 → 整条 halt。
+    // 修复后 pre-Read 直接登记 truncated:false，never-read + truncated 两道守卫一并解除，
+    // 声明产物整体覆盖放行。
+    seedSameTaskState('write-out');
+    writeFileSync(join(tmp, 'OUT.md'), 'A'.repeat(40_000));
+
+    const events = await collect(
+      runWorkflow(writeDef({ defLevel: ['OUT.md'] }), {}, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+  });
+
+  it('resume + args 用 ./相对路径、声明用裸文件名 → 归一化后等价命中', async () => {
+    seedSameTaskState('write-out');
+    writeFileSync(join(tmp, 'OUT.md'), 'old');
+
+    const events = await collect(
+      runWorkflow(
+        writeDef({ defLevel: ['OUT.md'], filePath: './OUT.md' }),
+        {},
+        ctx,
+      ),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+  });
+
+  it('目标文件不存在（新建场景）→ 不需要解守卫，正常写出', async () => {
+    const events = await collect(
+      runWorkflow(writeDef({ defLevel: ['OUT.md'] }), {}, ctx),
+    );
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(readFileSync(join(tmp, 'OUT.md'), 'utf8')).toBe('fresh-content');
+  });
+});

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

@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'bun:test';
+
+import { ALL_TOOLS } from '../../../src/tools/index.js';
+import type { Provider } from '../../../src/types.js';
+import { execToolStep } from '../src/stepExecutors/tool.js';
+import { VarStack, type RunContext } from '../src/types.js';
+
+const provider: Provider = {
+  name: 'test', baseURL: '', apiKey: '', model: 'fixture', contextWindow: 128_000,
+};
+
+describe('workflow deterministic tool capability boundary', () => {
+  test('a YAML tool step cannot restore WebBrowser removed by the host runtime', async () => {
+    const ctx: RunContext = {
+      provider,
+      history: [],
+      cwd: process.cwd(),
+      tools: ALL_TOOLS.filter((tool) => ['WebSearch', 'WebFetch'].includes(tool.name)),
+    };
+    const generator = execToolStep(
+      { id: 'hidden-browser', tool: 'WebBrowser', args: { action: 'navigate', url: 'https://example.com' } },
+      new VarStack(),
+      ctx,
+    );
+    await expect(generator.next()).rejects.toThrow(
+      '不在当前宿主授权的 Workflow 工具集中',
+    );
+  });
+});

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

@@ -0,0 +1,168 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  ALL_TOOLS,
+  type LoopEvent,
+  type Provider,
+  type ToolCallContext,
+  type ToolResult,
+  createAgentRuntimeContext,
+  createSessionState,
+} from '../../../src/plugin-sdk.js';
+import { execToolStep } from '../src/stepExecutors/tool.js';
+import { type RunContext, type StepResult, VarStack } from '../src/types.js';
+
+const provider: Provider = {
+  name: 'workflow-tool-test',
+  baseURL: '',
+  apiKey: '',
+  model: 'fixture',
+  contextWindow: 128_000,
+};
+
+async function collect(
+  generator: AsyncGenerator<LoopEvent, StepResult, void>,
+): Promise<{ events: LoopEvent[]; result: StepResult }> {
+  const events: LoopEvent[] = [];
+  while (true) {
+    const next = await generator.next();
+    if (next.done) return { events, result: next.value };
+    events.push(next.value);
+  }
+}
+
+function makeContext(
+  executeTool: NonNullable<RunContext['executeTool']>,
+): RunContext {
+  const sessionState = createSessionState();
+  sessionState.activeWorktree = {
+    id: 'wt_test',
+    path: '/tmp/workflow-active-worktree',
+    branch: 'workflow/test',
+    baseSha: 'deadbeef',
+    gitRoot: '/tmp/workflow-root',
+  };
+  return {
+    provider,
+    history: [],
+    cwd: '/tmp/workflow-root',
+    tools: ALL_TOOLS,
+    sessionState,
+    runtimeContext: createAgentRuntimeContext({
+      surface: 'workflow',
+      profile: 'main',
+      cwd: '/tmp/workflow-root',
+      workspaceId: 'workspace_test',
+      sessionId: 'session_test',
+      owner: 'local-owner',
+      memoryAccess: 'read-only',
+      interactiveAsk: false,
+    }),
+    promptCache: {
+      scopeKey: 'workflow-test-scope',
+      conversationKey: 'workflow-test-conversation',
+    },
+    executeTool,
+  };
+}
+
+describe('workflow deterministic tool runtime', () => {
+  test('all registered tools use the same generic deterministic node dispatcher', async () => {
+    const dispatched: string[] = [];
+    const ctx = makeContext(async (name) => {
+      dispatched.push(name);
+      return { ok: true, content: `${name} ok` };
+    });
+
+    for (const tool of ALL_TOOLS) {
+      const { result } = await collect(
+        execToolStep(
+          { id: `catalog_${tool.name}`, tool: tool.name, args: {} },
+          new VarStack(),
+          ctx,
+        ),
+      );
+      expect(result.raw).toMatchObject({ content: `${tool.name} ok` });
+    }
+
+    expect(dispatched).toEqual(ALL_TOOLS.map((tool) => tool.name));
+    expect(new Set(dispatched).size).toBe(ALL_TOOLS.length);
+  });
+
+  test('passes canonical runtime context and follows the active worktree cwd', async () => {
+    let captured: ToolCallContext | undefined;
+    const ctx = makeContext(async (_name, _args, _signal, context) => {
+      captured = context;
+      return { ok: true, content: 'ok' };
+    });
+
+    await collect(
+      execToolStep(
+        { id: 'context', tool: 'Read', args: { file_path: 'README.md' } },
+        new VarStack(),
+        ctx,
+      ),
+    );
+
+    expect(captured).toBeDefined();
+    expect(captured?.provider).toBe(provider);
+    expect(captured?.history).toBe(ctx.history);
+    expect(captured?.sessionState).toBe(ctx.sessionState);
+    expect(captured?.workspaceId).toBe('workspace_test');
+    expect(captured?.sessionId).toBe('session_test');
+    expect(captured?.memoryAccess).toBe('read-only');
+    expect(captured?.cwd).toBe('/tmp/workflow-active-worktree');
+    expect(captured?.toolCallId).toBe('wf_context');
+    expect(captured?.promptCache).toBe(ctx.promptCache);
+  });
+
+  test('streams tool progress and preserves structured result fields', async () => {
+    const metadata = {
+      kind: 'process_execution' as const,
+      shell: 'bash' as const,
+      mode: 'foreground' as const,
+      commandKind: 'test' as const,
+      status: 'completed' as const,
+      exitCode: 0,
+    };
+    const ctx = makeContext(async (_name, _args, _signal, context) => {
+      context?.reportProgress?.('running tests');
+      await Promise.resolve();
+      return {
+        ok: true,
+        content: 'tests passed',
+        metadata,
+        recovery: 'none',
+        sensitivity: 'local',
+        visionNote: 'verification image',
+      } satisfies ToolResult;
+    });
+
+    const { events, result } = await collect(
+      execToolStep(
+        { id: 'progress', tool: 'Bash', args: { command: 'bun test' } },
+        new VarStack(),
+        ctx,
+      ),
+    );
+
+    expect(events.map((event) => event.type)).toEqual([
+      'tool_start',
+      'tool_progress',
+      'tool_end',
+    ]);
+    expect(events[1]).toMatchObject({
+      type: 'tool_progress',
+      toolName: 'Bash',
+      toolCallId: 'wf_progress',
+      message: 'running tests',
+    });
+    expect(events[2]).toMatchObject({ type: 'tool_end', metadata });
+    expect(result.raw).toMatchObject({
+      metadata,
+      recovery: 'none',
+      sensitivity: 'local',
+      visionNote: 'verification image',
+    });
+  });
+});