minimal-agent 0.11.0 → 0.13.0

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

@@ -28,6 +28,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   rmSync,
   writeFileSync,
@@ -36,6 +37,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { createAgentRuntimeContext } from '../../../src/plugin-sdk.js';
 import { ALL_TOOLS } from '../../../src/tools/index.js';
 import { runWorkflow } from '../src/runner.js';
 import type { LoopEvent, Provider } from '../../../src/types.js';
@@ -43,6 +45,43 @@ import type { RunContext, WorkflowDef, WorkflowEvent } from '../src/types.js';
 
 type WfOrLoop = WorkflowEvent | LoopEvent;
 
+const DEFAULT_SESSION = 'test-session';
+
+function findInstanceDir(base: string, wfName: string, suffix = ''): string | null {
+  const wfDir = join(base, '.minimal-agent-workflow', wfName);
+  if (!existsSync(wfDir)) {
+    const legacyDir = suffix
+      ? join(base, '.minimal-agent-workflow', wfName + suffix)
+      : wfDir;
+    if (existsSync(legacyDir)) return legacyDir;
+    return null;
+  }
+
+  // Phase 3：session 化——实例目录名 = sessionId（默认 'default'）
+  const sessionDir = suffix
+    ? join(wfDir, DEFAULT_SESSION + suffix)
+    : join(wfDir, DEFAULT_SESSION);
+  if (existsSync(sessionDir)) return sessionDir;
+
+  // 旧布局兼容：wfDir 本身有 current.json（无子实例目录时判定为 legacy）
+  if (!suffix && existsSync(join(wfDir, 'current.json'))) {
+    try {
+      const entries = readdirSync(wfDir, { withFileTypes: true });
+      const hasInstanceSubdir = entries.some(
+        (e) => e.isDirectory() && /^[0-9a-f]{16}$/.test(e.name),
+      );
+      if (!hasInstanceSubdir) return wfDir;
+    } catch {
+      return wfDir;
+    }
+  }
+  return null;
+}
+
+function hasInstance(base: string, wfName: string, suffix = ''): boolean {
+  return findInstanceDir(base, wfName, suffix) !== null;
+}
+
 const fakeProvider: Provider = {
   name: 'test',
   baseURL: '',
@@ -72,7 +111,13 @@ describe('runner::pre-flight fresh 模式', () => {
       initWorkingDir: () => tmp,
       _resetWorkingDir: () => {},
     }));
-    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: [] };
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: tmp,
+      tools: [],
+      runtimeContext: createAgentRuntimeContext({ surface: 'workflow', profile: 'main', cwd: tmp, sessionId: DEFAULT_SESSION, owner: 'local-owner', interactiveAsk: false }),
+    };
   });
 
   afterEach(() => {
@@ -125,7 +170,13 @@ describe('runner::resume 与断点续执行', () => {
       initWorkingDir: () => tmp,
       _resetWorkingDir: () => {},
     }));
-    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: ALL_TOOLS };
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: tmp,
+      tools: ALL_TOOLS,
+      runtimeContext: createAgentRuntimeContext({ surface: 'workflow', profile: 'main', cwd: tmp, sessionId: DEFAULT_SESSION, owner: 'local-owner', interactiveAsk: false }),
+    };
   });
 
   afterEach(() => {
@@ -254,7 +305,13 @@ describe('runner::self_heal retry 机制', () => {
       initWorkingDir: () => tmp,
       _resetWorkingDir: () => {},
     }));
-    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: [] };
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: tmp,
+      tools: [],
+      runtimeContext: createAgentRuntimeContext({ surface: 'workflow', profile: 'main', cwd: tmp, sessionId: DEFAULT_SESSION, owner: 'local-owner', interactiveAsk: false }),
+    };
   });
 
   afterEach(() => {
@@ -350,9 +407,9 @@ describe('runner::self_heal retry 机制', () => {
 
     await collect(runWorkflow(def, {}, ctx));
 
-    // 成功后应 archive（活动目录改名 .done；E6 后按名隔离）
-    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'archive-test'))).toBe(false);
-    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'archive-test.done'))).toBe(true);
+    // 成功后应 archive（活动实例目录改名 .done；workflow 级父目录保留）
+    expect(hasInstance(tmp, 'archive-test')).toBe(false);
+    expect(hasInstance(tmp, 'archive-test', '.done')).toBe(true);
   });
 
   it('失败路径 → 保留状态目录供排查', async () => {
@@ -367,12 +424,12 @@ describe('runner::self_heal retry 机制', () => {
 
     await collect(runWorkflow(def, {}, ctx));
 
-    // 失败时应保留状态目录（E6 后按名隔离）
-    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'keep-state'))).toBe(true);
+    // 失败时应保留状态目录（workflow 级父目录 + 实例目录）
+    expect(hasInstance(tmp, 'keep-state')).toBe(true);
     // progress.md 应包含失败步骤信息
-    const progressPath = join(tmp, '.minimal-agent-workflow', 'keep-state', 'progress.md');
-    if (existsSync(progressPath)) {
-      const progress = readFileSync(progressPath, 'utf8');
+    const instDir = findInstanceDir(tmp, 'keep-state');
+    if (instDir) {
+      const progress = readFileSync(join(instDir, 'progress.md'), 'utf8');
       expect(progress).toContain('fail');
     }
   });

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

@@ -12,11 +12,12 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { createAgentRuntimeContext } from '../../../src/plugin-sdk.js';
 import { ALL_TOOLS } from '../../../src/tools/index.js';
 import { runWorkflow } from '../src/runner.js';
 import type { LoopEvent, Provider } from '../../../src/types.js';
@@ -41,6 +42,45 @@ async function collect(
 }
 
 const STATE_DIR = '.minimal-agent-workflow';
+// 集成测试统一用显式 sessionId（引擎对未指定 session 自动命名，见 runner 的
+// generateDefaultSessionId；测目录生命周期需要可预测的 session 名）
+const SESSION = 'test-session';
+
+function findInstanceDir(base: string, wfName: string, suffix = ''): string | null {
+  const wfDir = join(base, STATE_DIR, wfName);
+  if (!existsSync(wfDir)) {
+    // 旧布局兼容：wfDir 本身就是实例目录（wfName.done 形式）
+    const legacyDir = suffix
+      ? join(base, STATE_DIR, wfName + suffix)
+      : wfDir;
+    if (existsSync(legacyDir)) return legacyDir;
+    return null;
+  }
+
+  // Phase 3：session 化——实例目录名 = sessionId
+  const sessionDir = suffix
+    ? join(wfDir, SESSION + suffix)
+    : join(wfDir, SESSION);
+  if (existsSync(sessionDir)) return sessionDir;
+
+  // 旧布局兼容：wfDir 本身有 current.json（无子实例目录时判定为 legacy）
+  if (!suffix && existsSync(join(wfDir, 'current.json'))) {
+    try {
+      const entries = readdirSync(wfDir, { withFileTypes: true });
+      const hasInstanceSubdir = entries.some(
+        (e) => e.isDirectory() && /^[0-9a-f]{16}$/.test(e.name),
+      );
+      if (!hasInstanceSubdir) return wfDir;
+    } catch {
+      return wfDir;
+    }
+  }
+  return null;
+}
+
+function hasInstance(base: string, wfName: string, suffix = ''): boolean {
+  return findInstanceDir(base, wfName, suffix) !== null;
+}
 
 describe('workflow state-dir 生命周期', () => {
   let tmp: string;
@@ -55,7 +95,14 @@ describe('workflow state-dir 生命周期', () => {
       initWorkingDir: () => tmp,
       _resetWorkingDir: () => {},
     }));
-    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: ALL_TOOLS };
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: tmp,
+      tools: ALL_TOOLS,
+      // 显式 sessionId：目录名可预测，resume/归档断言稳定
+      runtimeContext: createAgentRuntimeContext({ surface: 'workflow', profile: 'main', cwd: tmp, sessionId: SESSION, owner: 'local-owner', interactiveAsk: false }),
+    };
   });
 
   afterEach(() => {
@@ -73,8 +120,8 @@ describe('workflow state-dir 生命周期', () => {
     const events = await collect(runWorkflow(def, {}, ctx));
     expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
     // 成功路径：活动目录被归档改名（completed 检测靠它），不留活动现场
-    expect(existsSync(join(tmp, STATE_DIR, 'ok'))).toBe(false);
-    expect(existsSync(join(tmp, STATE_DIR, 'ok.done'))).toBe(true);
+    expect(hasInstance(tmp, 'ok')).toBe(false);
+    expect(hasInstance(tmp, 'ok', '.done')).toBe(true);
   });
 
   it('halt → 保留状态目录 + progress.md 含失败那步', async () => {
@@ -91,9 +138,10 @@ describe('workflow state-dir 生命周期', () => {
     expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
 
     // 失败现场必须保留，供事后排查
-    const stateDir = join(tmp, STATE_DIR, 'boom');
-    expect(existsSync(stateDir)).toBe(true);
-    const progress = readFileSync(join(stateDir, 'progress.md'), 'utf8');
+    const stateDir = findInstanceDir(tmp, 'boom');
+    expect(stateDir).not.toBeNull();
+    expect(stateDir).toBeDefined();
+    const progress = readFileSync(join(stateDir as string, 'progress.md'), 'utf8');
     // 失败那步的 ✗ 行 + onFail 文案都应在 progress 里
     expect(progress).toContain('will_fail');
     expect(progress).toContain('nope');
@@ -106,7 +154,7 @@ describe('workflow state-dir 生命周期', () => {
       steps: [{ id: 'f', type: 'assert', condition: 'false', onFail: 'x' }],
     };
     await collect(runWorkflow(failDef, {}, ctx));
-    expect(existsSync(join(tmp, STATE_DIR, 'rerun'))).toBe(true); // 失败留下了
+    expect(hasInstance(tmp, 'rerun')).toBe(true); // 失败留下了
 
     // 第二次成功跑（同名同 inputs = 同任务 resume）：成功后归档 → 活动目录干净
     const okDef: WorkflowDef = {
@@ -115,8 +163,8 @@ describe('workflow state-dir 生命周期', () => {
       steps: [{ id: 'ok', type: 'assert', condition: 'true' }],
     };
     await collect(runWorkflow(okDef, {}, ctx));
-    expect(existsSync(join(tmp, STATE_DIR, 'rerun'))).toBe(false); // 不堆积
-    expect(existsSync(join(tmp, STATE_DIR, 'rerun.done'))).toBe(true);
+    expect(hasInstance(tmp, 'rerun')).toBe(false); // 不堆积
+    expect(hasInstance(tmp, 'rerun', '.done')).toBe(true);
   });
 
   it('E6：A 工作流失败现场不被不同名工作流 B 的运行破坏（按名隔离）', async () => {
@@ -131,7 +179,7 @@ describe('workflow state-dir 生命周期', () => {
       ],
     };
     await collect(runWorkflow(aDef, {}, ctx));
-    expect(existsSync(join(tmp, STATE_DIR, 'wf-a'))).toBe(true);
+    expect(hasInstance(tmp, 'wf-a')).toBe(true);
     expect(existsSync(join(tmp, 'A-PLAN.md'))).toBe(true);
 
     // 跑不同名工作流 B（曾经会清掉 A 的状态目录和产物——E6 事故）
@@ -144,7 +192,7 @@ describe('workflow state-dir 生命周期', () => {
     expect(evB.some((e) => e.type === 'workflow_done')).toBe(true);
 
     // A 的现场与产物完好，resume 能力保留
-    expect(existsSync(join(tmp, STATE_DIR, 'wf-a'))).toBe(true);
+    expect(hasInstance(tmp, 'wf-a')).toBe(true);
     expect(existsSync(join(tmp, 'A-PLAN.md'))).toBe(true);
   });
 });

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

@@ -24,6 +24,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { createAgentRuntimeContext } from '../../../src/plugin-sdk.js';
 import type { LoopEvent, Provider } from '../../../src/types.js';
 import {
   buildTaskArbitrator,
@@ -185,11 +186,13 @@ describe('workflowState::init × 仲裁（resume 保留现场 / new 清理重开
   });
 
   it('仲裁判 resume → 保留旧状态与产物、回放 checkpoint、带 prevGoal/supplementaryGoal', async () => {
-    // 旧任务：fresh + 完成一步 + 留产物（不 markDone = 未完成）
+    // 旧任务：fresh + 完成一步 + 留产物 + 留补充要求（不 markDone = 未完成）
     const s1 = new WorkflowState(tmp, 'plan');
     await s1.init('plan', { goal: '写产品架构 PPT' }, STEPS, 1, ['PLAN.md']);
     await s1.recordCheckpoint('s1', 'ok', { out: 'v1' }, {});
+    await s1.appendSupplement('用户要求加一章');
     writeFileSync(join(tmp, 'PLAN.md'), '# 半成品');
+    const oldDir = s1.dir;
 
     // 新输入「继续」（hash 必然不等）+ 仲裁器判 resume
     const s2 = new WorkflowState(tmp, 'plan');
@@ -202,6 +205,10 @@ describe('workflowState::init × 仲裁（resume 保留现场 / new 清理重开
     expect(r.supplementaryGoal).toBe('继续');
     // 现场未被清理
     expect(existsSync(join(tmp, 'PLAN.md'))).toBe(true);
+    // 回归：resume 后实例目录必须仍指向旧任务（否则 supplements / checkpoint 全写丢，
+    // 断点续跑静默失效——曾因 finally 误把 this.dir 改回新 hash 目录）
+    expect(s2.dir).toBe(oldDir);
+    expect(await s2.readSupplements()).toEqual(['用户要求加一章']);
   });
 
   it('仲裁判 new → 走 new-task 清理重开', async () => {
@@ -257,7 +264,9 @@ describe('workflowState::init × 仲裁（resume 保留现场 / new 清理重开
     expect(r.mode).toBe('fresh');
     expect(arbCalled).toBe(0);
     // A 的现场完好（曾经会被 B 的 new-task 清掉——E6 事故）
-    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'other-wf', 'current.json'))).toBe(true);
+    // 新布局：current.json 在实例子目录里；旧布局兼容时直接在 wfDir 下
+    const aDir = sA.dir;
+    expect(existsSync(join(aDir, 'current.json'))).toBe(true);
   });
 });
 
@@ -276,7 +285,14 @@ describe('runWorkflow × 仲裁延续（端到端）', () => {
       initWorkingDir: () => tmp,
       _resetWorkingDir: () => {},
     }));
-    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: [] };
+    ctx = {
+      provider: fakeProvider,
+      history: [],
+      cwd: tmp,
+      tools: [],
+      // 显式 sessionId：两次 runWorkflow 同 session，仲裁「继续」才能 resume 旧任务
+      runtimeContext: createAgentRuntimeContext({ surface: 'workflow', profile: 'main', cwd: tmp, sessionId: 'test-session', owner: 'local-owner', interactiveAsk: false }),
+    };
   });
   afterEach(() => {
     delete process.env.MINIMAL_AGENT_CWD;

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

@@ -67,9 +67,10 @@ describe('任务身份生命周期（L2 completed / L3 new-task 清产物）', (
     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);
+    // 归档后活动实例被改名 .done（workflow 级父目录保留——里面可能有多个实例）
+    expect(existsSync(join(tmp, '.minimal-agent-workflow', 'plan'))).toBe(true);
+    expect(existsSync(s1.dir + '.done')).toBe(true);
+    expect(existsSync(s1.dir)).toBe(false);
 
     // 第二次：同 goal 重跑 → completed（经 .done 检测），报真实产物
     const s2 = new WorkflowState(tmp, 'plan');
@@ -104,8 +105,9 @@ describe('任务身份生命周期（L2 completed / L3 new-task 清产物）', (
     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);
+    expect(r2.archivedTo).toBeDefined();
+    expect(existsSync(join(tmp, r2.archivedTo as string, 'PLAN.md'))).toBe(true);
   });
 
   it('legacy 状态文件（无 artifacts 字段）+ 同名 workflow 换 goal → new-task 用本次声明清单兜底清理', async () => {
@@ -128,8 +130,9 @@ describe('任务身份生命周期（L2 completed / L3 new-task 清产物）', (
     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);
+    expect(r.archivedTo).toBeDefined();
+    expect(existsSync(join(tmp, r.archivedTo as string, 'PLAN.md'))).toBe(true);
   });
 
   it('/new 后孤儿产物：无任何状态但声明产物已存在 → fresh 启动时清理（全新任务从干净状态开始）', async () => {
@@ -141,8 +144,59 @@ describe('任务身份生命周期（L2 completed / L3 new-task 清产物）', (
     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']);
+    expect(r.archivedTo).toBeDefined();
+    expect(existsSync(join(tmp, r.archivedTo as string, 'PLAN.md'))).toBe(true);
+  });
+
+  it('A4：归档保留相对路径结构，只归档声明产物、不碰未声明文件', async () => {
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(tmp, 'out'), { recursive: true });
+    const s1 = new WorkflowState(tmp, 'plan');
+    await s1.init('plan', { goal: '目标A' }, STEPS, 1, ['out/PLAN.md']);
+    writeFileSync(join(tmp, 'out', 'PLAN.md'), '# A');
+    writeFileSync(join(tmp, 'out', 'USER-OWN.md'), '# 用户自己的文件');
+
+    const s2 = new WorkflowState(tmp, 'plan');
+    const r2 = await s2.init('plan', { goal: '目标B' }, STEPS, 1, ['out/PLAN.md']);
+    expect(r2.mode).toBe('new-task');
+    expect(existsSync(join(tmp, 'out', 'PLAN.md'))).toBe(false);
+    expect(existsSync(join(tmp, 'out', 'USER-OWN.md'))).toBe(true);
+    expect(existsSync(join(tmp, r2.archivedTo as string, 'out', 'PLAN.md'))).toBe(true);
+  });
+
+  it('B8：声明产物支持 glob（out/*.md），new-task 清理时展开为实际文件归档', async () => {
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(tmp, 'out'), { recursive: true });
+    const s1 = new WorkflowState(tmp, 'research');
+    await s1.init('research', { goal: '目标A' }, STEPS, 1, ['out/deep-dive-*.md']);
+    writeFileSync(join(tmp, 'out', 'deep-dive-a.md'), '# A');
+    writeFileSync(join(tmp, 'out', 'deep-dive-b.md'), '# B');
+    writeFileSync(join(tmp, 'out', 'notes.txt'), '# 不匹配 md');
+
+    const s2 = new WorkflowState(tmp, 'research');
+    const r2 = await s2.init('research', { goal: '目标B' }, STEPS, 1, ['out/deep-dive-*.md']);
+    expect(r2.mode).toBe('new-task');
+    expect(existsSync(join(tmp, 'out', 'deep-dive-a.md'))).toBe(false);
+    expect(existsSync(join(tmp, 'out', 'deep-dive-b.md'))).toBe(false);
+    expect(existsSync(join(tmp, 'out', 'notes.txt'))).toBe(true);
+    const trash = join(tmp, r2.archivedTo as string);
+    expect(existsSync(join(trash, 'out', 'deep-dive-a.md'))).toBe(true);
+    expect(existsSync(join(trash, 'out', 'deep-dive-b.md'))).toBe(true);
+  });
+
+  it('B8：越界 glob（../x*）不展开不清理（fail-closed）', async () => {
+    writeFileSync(join(tmp, 'PLAN.md'), '# inside');
+    const outside = mkdtempSync(join(tmpdir(), 'wf-outside-'));
+    try {
+      writeFileSync(join(outside, 'secret.md'), '# outside');
+      const s = new WorkflowState(tmp, 'plan');
+      const r = await s.init('plan', { goal: '目标A' }, STEPS, 1, ['../x*.md', 'PLAN.md']);
+      expect(r.mode).toBe('fresh');
+      expect(existsSync(join(outside, 'secret.md'))).toBe(true);
+      expect(existsSync(join(tmp, 'PLAN.md'))).toBe(false);
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
   });
 
   it('resume 恢复点用最后完成步的【索引】而非 checkpoint 计数（when 跳过步不再被重复执行）', async () => {

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',
+    });
+  });
+});

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

@@ -70,11 +70,11 @@ describe('workflows/webppt.yaml', () => {
       expect(String(s.title)).toContain('/11');
     }
 
-    // 收尾报告 echo；artifacts 只列最终交付物、不在被 rm 的 ./build 下
+    // 收尾报告 echo；artifacts 只列最终交付物、不在被 rm 的 out/webppt/${session}/build 下
     expect(def.steps.find((s) => s.id === 'final_report')?.type).toBe('echo');
     const declared = def.artifacts ?? [];
-    expect(declared).toContain('./out/deck.pptx');
-    for (const a of declared) expect(a.startsWith('./build')).toBe(false);
+    expect(declared).toContain('out/webppt/${session}/deck.pptx');
+    for (const a of declared) expect(a.startsWith('out/webppt/${session}/build')).toBe(false);
   });
 
   it('需求分析步：style 为空时必问视觉样式（VI 选项 + 自定义输入），AskUserQuestion 可用', async () => {
@@ -199,7 +199,7 @@ describe('workflows/webppt.yaml', () => {
     // 配图分流闸门：image_plan_lint 的 --outline 直接吃 design.json
     const gate = def.steps.find((s) => s.id === 'stage_img_route_gate');
     expect(String(gate?.agent)).toContain('image_plan_lint.py');
-    expect(String(gate?.agent)).toContain('--outline ./build/design.json');
+    expect(String(gate?.agent)).toContain('--outline out/webppt/${session}/build/design.json');
     expect(String(gate?.done_when)).toContain('img_route_ok');
     // 顺序：build_loop → img_route_gate → gen_images
     expect(ids.indexOf('stage_img_route_gate')).toBeGreaterThan(ids.indexOf('stage_build_loop'));

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

@@ -3,7 +3,7 @@
  * ------------------------------------------------------------
  * 锁定 workflows/word.yaml（素材驱动知乎深度长文 Word 工作流）的
  * 「可解析 + 关键骨架」：
- *   - name=word，最终产物是 ./out/article.docx
+ *   - name=word，最终产物是 out/word/${session}/article.docx
  *   - inputs 支持 topic(greedy) / source / out / image_intensity / quality / debug_keep_build
  *   - Markdown-first：material → outline → article.md → image_map/img_plan → docx skill → OPC
  *   - 客户图必须使用；需要解释型视觉时积极文生图，提示词必须结合上下文
@@ -32,8 +32,8 @@ describe('workflows/word.yaml（素材驱动·知乎深度长文 Word）', () =>
     expect(def.description).toContain('知乎深度文章');
 
     const declared = def.artifacts ?? [];
-    expect(declared).toContain('./out/article.docx');
-    for (const a of declared) expect(a.startsWith('./build')).toBe(false);
+    expect(declared).toContain('out/word/${session}/article.docx');
+    for (const a of declared) expect(a.startsWith('out/word/${session}/build')).toBe(false);
 
     const inputNames = (def.inputs ?? []).map((i) => i.name);
     expect(inputNames).toEqual(
@@ -49,7 +49,7 @@ describe('workflows/word.yaml（素材驱动·知乎深度长文 Word）', () =>
     expect(inputNames[0]).toBe('topic');
     expect((def.inputs ?? []).find((i) => i.name === 'topic')?.greedy).toBe(true);
     expect((def.inputs ?? []).find((i) => i.name === 'out')?.default).toBe(
-      './out/article.docx',
+      'out/word/${session}/article.docx',
     );
   });
 
@@ -163,11 +163,11 @@ describe('workflows/word.yaml（素材驱动·知乎深度长文 Word）', () =>
     const extract = def.steps.find((s) => s.id === 'stage_extract');
     const command = String(extract?.args?.command ?? '');
 
-    expect(command).toContain('./build/source.md');
-    expect(command).toContain('rm -rf ./build/assets');
-    expect(command).toContain('mkdir -p ./build/assets');
-    expect(command).toContain('./build/word_topic_image_gate.json');
-    expect(command).toContain('./build/word_topic_image_gate.md');
+    expect(command).toContain('out/word/${session}/build/source.md');
+    expect(command).toContain('rm -rf out/word/${session}/build/assets');
+    expect(command).toContain('mkdir -p out/word/${session}/build/assets');
+    expect(command).toContain('out/word/${session}/build/word_topic_image_gate.json');
+    expect(command).toContain('out/word/${session}/build/word_topic_image_gate.md');
   });
 
   it('生成配图失败时会在导出前硬失败，不会把渐变占位图交付进 Word', async () => {