minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/src/stepExecutors/tool.ts

@@ -1,274 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/tool.ts —— tool step 执行
- * ------------------------------------------------------------
- *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
- *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
- *
- *  v2（P1 TUI 可见）：本执行器改为 AsyncGenerator，在调 executeTool 前后
- *  yield 通用 tool_start / tool_end LoopEvent —— 这样 workflow 的 tool 步骤
- *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述）。
- *
- *  v0.9.3（上下文统一修复）：tool 步骤执行后把工具调用摘要写入 ctx.history，
- *  让后续 agent/llm/skill 步骤（走 runQuery → LLM）能自然看到前面步骤的工作成果，
- *  不再依赖 VarStack 变量插值作为唯一的信息传递通道。
- *  这实现了"一套上下文"架构：workflow 的每一步都在共享的 TAOR history 中留痕。
- *
- *  capture 字段（支持点路径）：
- *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
- *    - `{ result: var_name }`       同义，给"无结构化字段"工具用
- *    - `{ args.content: var_name }` 绑插值后传给工具的入参（如真正写入的内容）
- *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
- * ============================================================
- */
-
-import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-import {
-  type LoopEvent,
-  type ToolResult,
-  executeTool,
-  getToolByName,
-  recordRead,
-} from '../../../../src/plugin-sdk.js';
-import { interpolateDeep } from '../expressions.js';
-import {
-  buildWorkflowToolContext,
-  effectiveWorkflowCwd,
-} from '../toolRuntime.js';
-import { safeArtifactPath, type RunContext, type StepDef, type StepResult, type VarStack } from '../types.js';
-
-export async function* execToolStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): AsyncGenerator<LoopEvent, StepResult, void> {
-  if (!step.tool) throw new Error(`step ${step.id}: 缺少 tool 字段`);
-  const tool = getToolByName(step.tool);
-  if (!tool) throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
-  if (!ctx.tools.some((available) => available.name === tool.name)) {
-    throw new Error(
-      `step ${step.id}: 工具 "${tool.name}" 不在当前宿主授权的 Workflow 工具集中`,
-    );
-  }
-
-  // 未定义变量插值可见化（args 里静默空串会让工具拿到空路径/空内容）
-  const missing: string[] = [];
-  const args = interpolateDeep(step.args ?? {}, vars, {
-    onMissing: (e) => missing.push(e),
-  });
-  if (missing.length > 0) {
-    yield {
-      type: 'warning',
-      message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-    };
-  }
-  const argsJson = JSON.stringify(args);
-  const toolCallId = `wf_${step.id}`;
-  const argsPreview =
-    argsJson.length > 80 ? `${argsJson.slice(0, 80)}…` : argsJson;
-
-  yield {
-    type: 'tool_start',
-    toolName: tool.name,
-    toolCallId,
-    argsPreview,
-    argsFriendly: friendlyToolDesc(tool.name, args as Record<string, unknown>),
-  };
-
-  // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
-  // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
-  // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
-  // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
-  // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
-  // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
-  // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
-  await preReadDeclaredArtifact(
-    tool,
-    args as Record<string, unknown>,
-    step,
-    ctx,
-  );
-
-  // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
-  // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
-  const pendingProgress: LoopEvent[] = [];
-  let wakeProgress: (() => void) | undefined;
-  const toolContext = buildWorkflowToolContext(
-    step,
-    ctx,
-    toolCallId,
-    (message, detail) => {
-      pendingProgress.push({
-        type: 'tool_progress',
-        toolName: tool.name,
-        toolCallId,
-        message,
-        detail,
-      });
-      wakeProgress?.();
-    },
-  );
-  if ('error' in toolContext) {
-    throw new Error(`step ${step.id}: ${toolContext.error}`);
-  }
-
-  const dispatch = ctx.executeTool ?? executeTool;
-  let settled = false;
-  let result: ToolResult | undefined;
-  void dispatch(tool.name, argsJson, ctx.signal, toolContext)
-    .then((value) => {
-      result = value;
-    })
-    .catch((error: unknown) => {
-      result = {
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      };
-    })
-    .finally(() => {
-      settled = true;
-      wakeProgress?.();
-    });
-
-  while (!settled || pendingProgress.length > 0) {
-    const progress = pendingProgress.shift();
-    if (progress) {
-      yield progress;
-      continue;
-    }
-    await new Promise<void>((resolveWake) => {
-      wakeProgress = resolveWake;
-      if (settled || pendingProgress.length > 0) resolveWake();
-    });
-    wakeProgress = undefined;
-  }
-  if (!result) throw new Error(`step ${step.id}: 工具执行未返回结果`);
-
-  yield {
-    type: 'tool_end',
-    toolName: tool.name,
-    toolCallId,
-    ok: result.ok,
-    content: result.ok ? result.content : result.error,
-    metadata: result.metadata,
-  };
-
-  if (!result.ok) {
-    throw new Error(result.error);
-  }
-  const content = result.content;
-
-  // ════ v0.9.3：上下文统一 —— 把工具调用写入共享 history ════
-  // 后续 agent/llm/skill 步骤走 runQuery() 时，LLM 能在上下文中看到
-  // 这步做了什么（与正常 TAOR 循环中 tool_call → tool_result 的记录方式一致）。
-  // 只记录精简摘要（不把完整工具回执塞入 history，避免 token 浪费）。
-  const summary =
-    content.length > 500
-      ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
-      : content;
-  ctx.history.push({
-    role: 'assistant',
-    content: `[workflow:${step.id}] ✅ ${tool.name} 执行完成：${summary}`,
-    timestamp: Date.now(),
-    id: randomUUID(),
-  });
-
-  // ⚠️ 工具返回的图片**不能丢**。此前这里只取 content，`visionImages` 被静默丢弃 ——
-  // 于是任何「截图/看图」类工作流都拿不到产物，而且不会报错，只是后面的评估步没图可看。
-  // 取路径而不是整个 ImageInputSpec：yaml 侧要的是能 capture、能传给 llm 步 `images:`
-  // 的字符串；结构体传下去反而要每个消费方各自解包。
-  const images = (result.visionImages ?? [])
-    .map((image) => (typeof image.source === 'string' ? image.source : ''))
-    .filter((path) => path.length > 0);
-
-  return {
-    raw: {
-      content,
-      result: content,
-      args,
-      images,
-      metadata: result.metadata,
-      recovery: result.recovery,
-      sensitivity: result.sensitivity,
-      visionNote: result.visionNote,
-    },
-    preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
-  };
-}
-
-/**
- * 写类 tool 步的目标文件若命中【安全的声明产物】且已存在 → pre-Read 解除内核守卫。
- *
- * 路径归一化：artifacts 声明相对 cwd；args.file_path 可能是 ./相对 或 绝对，
- * 双方都 resolve(cwd, …) 后比较（win32 文件系统大小写不敏感 → lowercase 比较；
- * 其余平台保持大小写敏感，避免 Plan.md / plan.md 误判同文件）。
- *
- * 安全守卫（修复路径遍历）：
- *   · 声明的 artifacts 路径先经 safeArtifactPath 校验【必须落在 cwd 内】，
- *     越界声明直接从命中列表移除——不解守卫，让内核写保护照常生效（fail-closed）。
- *   · args.file_path 目标自身也做 cwd 内校验：目标越界（工作流步骤想写 cwd 外）
- *     → 同样不解守卫，让写工具在执行时自己报错（通常是权限/文件不存在提示，
- *        而不是静默放行盲写，双重保险）。
- */
-async function preReadDeclaredArtifact(
-  tool: { name: string; isReadOnly?: boolean },
-  args: Record<string, unknown>,
-  step: StepDef,
-  ctx: RunContext,
-): Promise<void> {
-  if (tool.isReadOnly !== false) return; // 只对写类工具生效
-  if (typeof args.file_path !== 'string') return;
-
-  const cwd = effectiveWorkflowCwd(ctx);
-  const norm = (p: string): string => {
-    const abs = resolve(cwd, p);
-    return process.platform === 'win32' ? abs.toLowerCase() : abs;
-  };
-
-  // 1. 目标文件先过 cwd 安全关（越界直接不解守卫）
-  const targetRaw = String(args.file_path);
-  const targetSafe = safeArtifactPath(cwd, targetRaw);
-  if (targetSafe === null) return;
-  const target = norm(targetSafe);
-
-  // 2. 声明产物过 cwd 安全关（过滤掉越界的声明）
-  const rawDeclared = [...(ctx.declaredArtifacts ?? []), ...(step.artifacts ?? [])];
-  const declaredAbs: string[] = [];
-  for (const raw of rawDeclared) {
-    const safe = safeArtifactPath(cwd, raw);
-    if (safe !== null) declaredAbs.push(norm(safe));
-  }
-  if (!declaredAbs.some((a) => a === target)) return;
-
-  const abs = resolve(cwd, targetSafe);
-  if (!existsSync(abs)) return; // 新建文件不需要解守卫
-
-  // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
-  //   1. 声明产物本就要被本步整体覆盖，旧内容无需进上下文/烧 token；
-  //   2. 真 Read 大文件会触发字符上限截断（read.ts → recordRead({truncated:true})），
-  //      反而踩中 Write 的「截断禁写」硬守卫（write.ts: existsSync && wasTruncated → 拒绝），
-  //      正是本步要解除的同一道墙——曾导致 plan.yaml 回写变长的 PLAN.md 时 halt
-  //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
-  //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
-  // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
-  recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
-}
-
-/**
- * 给 tool_start 生成人话描述（LiveArea spinner 行用）。
- */
-function friendlyToolDesc(
-  toolName: string,
-  args: Record<string, unknown>,
-): string {
-  const key = ['file_path', 'command', 'query', 'pattern', 'path', 'url'].find(
-    (k) => typeof args[k] === 'string',
-  );
-  if (!key) return toolName;
-  const val = String(args[key]);
-  const short = val.length > 60 ? `${val.slice(0, 60)}…` : val;
-  return `${toolName} ${short}`;
-}

package/plugins/workflow-runner/src/stepExecutors/verify.js

@@ -1,61 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/verify.ts —— verify step 执行
- * ------------------------------------------------------------
- *  复用内核共享验证基础设施（经 plugin-sdk 门面取 runVerification/parseCheckString），
- *  支持 shell / file_exists / file_contains / test_count 四种检查。
- *
- *  与 assert 的区别：
- *    - assert: evalExpr 表达式（轻量，适合简单文件存在判断）
- *    - verify: 完整检查器（重量，支持命令执行/正则匹配/测试计数）
- * ============================================================
- */
-import { parseCheckString, runVerification } from '../../../../src/plugin-sdk.js';
-import { interpolate } from '../expressions.js';
-import { effectiveWorkflowCwd } from '../toolRuntime.js';
-export async function execVerifyStep(step, vars, ctx) {
-    // 兼容两种格式：YAML 数组 或逗号分隔字符串。
-    // 关键：【先插值再按逗号分割】。checks 可能是 "${verify_checks}" 这类模板，插值后才
-    // 展开成逗号分隔的多项（如 "shell:bun test,file_exists:x"）。若先分割再插值，整段模板
-    // 会被当成一项，解析时 value 混入逗号、多项检查失效（ralph-loop 的 run_verify 即如此）。
-    let rawChecks;
-    if (Array.isArray(step.checks) && step.checks.length > 0) {
-        rawChecks = step.checks
-            .flatMap((s) => interpolate(s, vars).split(','))
-            .map((s) => s.trim())
-            .filter(Boolean);
-    }
-    else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
-        rawChecks = interpolate(step.checks, vars)
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean);
-    }
-    else {
-        throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
-    }
-    // 解析每条已插值的 check 字符串（插值后若整体为空——如 ${verify_checks} 取到空串——
-    // 则 checks 为空，runVerification 视为"无检查项"通过；ralph-loop 另有 when 守卫不会走到这）
-    const checks = [];
-    for (const raw of rawChecks) {
-        const check = parseCheckString(raw);
-        if (!check) {
-            throw new Error(`step ${step.id}: 无法解析 check "${raw}"，格式应为 "type:value"`);
-        }
-        checks.push(check);
-    }
-    // 执行所有检查。
-    // cwd 必须和写入侧同源：会话进了 session worktree 时产物落在 worktree 里，
-    // 验收若锚原 workspace 会在空目录找文件，恒判失败并触发无意义的重试。
-    const result = await runVerification(checks, effectiveWorkflowCwd(ctx));
-    if (!result.passed) {
-        const msg = step.onFail
-            ? interpolate(step.onFail, vars)
-            : `verify 失败: ${result.summary}`;
-        throw new Error(msg);
-    }
-    return {
-        raw: { passed: true, summary: result.summary, details: result.details },
-        preview: result.summary,
-    };
-}

package/plugins/workflow-runner/src/stepExecutors/verify.ts

@@ -1,72 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/verify.ts —— verify step 执行
- * ------------------------------------------------------------
- *  复用内核共享验证基础设施（经 plugin-sdk 门面取 runVerification/parseCheckString），
- *  支持 shell / file_exists / file_contains / test_count 四种检查。
- *
- *  与 assert 的区别：
- *    - assert: evalExpr 表达式（轻量，适合简单文件存在判断）
- *    - verify: 完整检查器（重量，支持命令执行/正则匹配/测试计数）
- * ============================================================
- */
-
-import { parseCheckString, runVerification, type Check } from '../../../../src/plugin-sdk.js';
-import { interpolate } from '../expressions.js';
-import { effectiveWorkflowCwd } from '../toolRuntime.js';
-import type { RunContext, StepDef, StepResult, VarStack } from '../types.js';
-
-export async function execVerifyStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): Promise<StepResult> {
-  // 兼容两种格式：YAML 数组 或逗号分隔字符串。
-  // 关键：【先插值再按逗号分割】。checks 可能是 "${verify_checks}" 这类模板，插值后才
-  // 展开成逗号分隔的多项（如 "shell:bun test,file_exists:x"）。若先分割再插值，整段模板
-  // 会被当成一项，解析时 value 混入逗号、多项检查失效（ralph-loop 的 run_verify 即如此）。
-  let rawChecks: string[];
-  if (Array.isArray(step.checks) && step.checks.length > 0) {
-    rawChecks = (step.checks as string[])
-      .flatMap((s) => interpolate(s, vars).split(','))
-      .map((s) => s.trim())
-      .filter(Boolean);
-  } else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
-    rawChecks = interpolate(step.checks as string, vars)
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-  } else {
-    throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
-  }
-
-  // 解析每条已插值的 check 字符串（插值后若整体为空——如 ${verify_checks} 取到空串——
-  // 则 checks 为空，runVerification 视为"无检查项"通过；ralph-loop 另有 when 守卫不会走到这）
-  const checks: Check[] = [];
-  for (const raw of rawChecks) {
-    const check = parseCheckString(raw);
-    if (!check) {
-      throw new Error(
-        `step ${step.id}: 无法解析 check "${raw}"，格式应为 "type:value"`,
-      );
-    }
-    checks.push(check);
-  }
-
-  // 执行所有检查。
-  // cwd 必须和写入侧同源：会话进了 session worktree 时产物落在 worktree 里，
-  // 验收若锚原 workspace 会在空目录找文件，恒判失败并触发无意义的重试。
-  const result = await runVerification(checks, effectiveWorkflowCwd(ctx));
-
-  if (!result.passed) {
-    const msg = step.onFail
-      ? interpolate(step.onFail, vars)
-      : `verify 失败: ${result.summary}`;
-    throw new Error(msg);
-  }
-
-  return {
-    raw: { passed: true, summary: result.summary, details: result.details },
-    preview: result.summary,
-  };
-}

package/plugins/workflow-runner/src/stepPipeline.js

@@ -1,277 +0,0 @@
-/**
- * ============================================================
- *  stepPipeline.ts —— 「一步算完成」的唯一实现
- * ------------------------------------------------------------
- *  ⚠️ 这个文件存在的理由是一次真实的架构事故。
- *
- *  重构前，「提交一步」这套动作（绑 capture → 累加目标补充 → 写 progress →
- *  落 vars → 记 checkpoint → 发 step_end）**没有单一实现**，被 `runSteps` 里的
- *  各个内联块各抄一份。抄到什么程度：
- *
- *      recordCheckpoint  × 7      appendProgress   × 17
- *      writeVars         × 7      step_end 事件    × 19
- *      bindCapture       × 3      collectCaptured  × 5
- *
- *  而且**已经漂移出真 bug**：7 处 checkpoint 里，`set` 传 `resolved`、
- *  `echo` 传 `{}`、其余 5 处传 `collectCaptured(step.capture, vars)`。
- *  顺着查下去发现 `echo` / `set` 从不调 `bindCapture` ——
- *  **它们静默忽略 `capture:`**：yaml 作者写了既不报错也不生效，
- *  resume 时那个变量也回放不出来。又一次「静默失效」。
- *
- *  所以这里的规则是硬的：**任何 step 完成后都必须经过 `commitStep`。**
- *  新增 step 类型时不要再自己写这套 —— 抄一份就是又埋一颗漂移的种子。
- *  `plugins/workflow-runner/test/stepPipeline.test.ts` 钉着这条。
- * ============================================================
- */
-import { isMaxTurnsCutoff } from './agentCommon.js';
-import { runRecovery } from './recovery.js';
-import { normalizeCapture } from './types.js';
-const WF_PLUGIN_ID = 'workflow-runner';
-/** 读 `a.b.c` 形式的嵌套字段。 */
-function readPath(root, path) {
-    const parts = path.split('.');
-    let cur = root;
-    for (const p of parts) {
-        if (cur == null || typeof cur !== 'object')
-            return undefined;
-        cur = cur[p];
-    }
-    return cur;
-}
-/**
- * 把本步产出绑到变量上，**并把「绑了个空」响亮说出来**。
- *
- * ⚠️ `capture` 的写法是 `{ 结果字段: 变量名 }`。写反了（`{ 变量名: 结果字段 }`）
- * 语法完全合法、加载期查不出来，运行时只是安静地绑一个 undefined —— 然后：
- *   · `${varName}` 插值发一条「模板变量未定义」的 warning，但那条指向的是**使用处**，
- *     看着像是「后面那步写错了」，而真正错的是**几十行之前的 capture**
- *   · 更糟的是 assert：条件直接判假，用户看到的是 onFail 里那段业务文案，
- *     与真实原因毫无关系，排查方向被彻底带偏
- *
- * 实测踩过两次（`adaptive-research.yaml` 绑 `content` 而 agent 步只有 `text`；
- * `wechat-reading-shots.yaml` 把 `text: pager` 写反成 `pager: text`）。
- */
-export function bindCapture(captureMap, result, vars, stepId) {
-    const warnings = [];
-    for (const [resultField, varName] of Object.entries(normalizeCapture(captureMap))) {
-        const value = resultField.includes('.')
-            ? readPath(result.raw, resultField)
-            : result.raw[resultField];
-        if (value === undefined) {
-            const available = Object.keys(result.raw);
-            warnings.push(`step "${stepId ?? '?'}": capture 取不到字段 \`${resultField}\`，变量 `
-                + `\`${varName}\` 绑成了 undefined。本步实际可绑的字段：`
-                + `${available.length ? available.map((k) => `\`${k}\``).join('、') : '（无）'}。`
-                + `⚠️ 写法是 { 结果字段: 变量名 }，检查是否写反了。`);
-        }
-        vars.set(varName, value);
-    }
-    return warnings;
-}
-/** 取本步 capture 出的 { varName: value }，供 checkpoint 记录（resume 回放用）。 */
-export function collectCaptured(captureMap, vars) {
-    if (!captureMap)
-        return {};
-    const out = {};
-    for (const varName of Object.values(normalizeCapture(captureMap))) {
-        out[varName] = vars.get(varName);
-    }
-    return out;
-}
-/** 从 StepResult 里取「可当作用户补充要求」的那段文本。 */
-function supplementTextOf(result) {
-    return typeof result.raw.text === 'string' && result.raw.text.trim()
-        ? result.raw.text
-        : String(result.raw.result ?? result.preview ?? '');
-}
-/**
- * 提交一步：capture → goal_supplement → progress → vars → checkpoint → step_end。
- *
- * **所有 step 类型的唯一收口。** 见文件头注：抄第二份就是埋漂移。
- */
-export async function* commitStep(input) {
-    const { step, result, kind, vars, state, cp } = input;
-    if (step.capture) {
-        for (const message of bindCapture(step.capture, result, vars, step.id)) {
-            yield { type: 'warning', message };
-        }
-    }
-    // goal_supplement：本步产出作为用户补充要求贯穿后续每一步（如 stage0 澄清结论）
-    if (step.goal_supplement) {
-        await input.addGoalSupplement(supplementTextOf(result));
-    }
-    await state.appendProgress(input.progressLine ?? `✓ ${step.id} (${kind})`);
-    await state.writeVars(vars.snapshot());
-    // checkpoint：记录范围见 CpScope（顶层步 + 顶层 loop 的 do[] 一层）。
-    //
-    // 回放变量 = 本步**引入的**变量（`replayVars`，目前只有 set）
-    //          + 作者**显式声明**要捕获的变量（`capture`）。
-    // 两者不能互相替代：set 步通常没有 capture，只记 collectCaptured 会得到 {} ——
-    // resume 跳过它之后下游断言就查不到那个变量了（engineRobustness 抓过这个回归）。
-    if (cp) {
-        await state.recordCheckpoint(cp.name(step.id), result.preview, { ...(result.replayVars ?? {}), ...collectCaptured(step.capture, vars) }, vars.snapshot());
-    }
-    yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: true,
-        output: result.preview,
-    };
-}
-/** 可中断的 sleep：中断时立刻返回，不把整轮退避耗完。 */
-function sleepInterruptible(ms, signal) {
-    return new Promise((res) => {
-        if (signal?.aborted)
-            return res();
-        const t = setTimeout(done, ms);
-        function done() {
-            clearTimeout(t);
-            signal?.removeEventListener('abort', done);
-            res();
-        }
-        signal?.addEventListener('abort', done, { once: true });
-    });
-}
-/**
- * 执行一个动作步：in-run 重试 → onError 三态 → 统一提交。
- *
- * 三条语义原样保留（都是实测踩出来的）：
- *   · `max_retries` 是**额外**重试次数，总尝试 = 1 + maxRetries
- *   · 退避是**线性**的（delayBase × attempt）；maxTurns 截断走 `max_turns_retry_delay_ms`，
- *     缺省 0 = 立即续跑（长文档类工作流才需要给模型端留恢复窗口）
- *   · `onError:'recover'` 有**验证闸门**：只有恢复 agent 真正交付才绑 capture 走下去，
- *     显式放弃 / 产出不可信一律带原因 honest halt，绝不盲绑脏值
- */
-export async function* runStepWithRetry(input) {
-    const { step, kind, vars, ctx, state, cp } = input;
-    const maxRetries = step.max_retries ?? ctx.selfHealMaxRetries ?? 0;
-    let attempt = 0;
-    while (true) {
-        try {
-            const result = yield* input.execute();
-            yield* commitStep({
-                step,
-                result,
-                kind,
-                vars,
-                ctx,
-                state,
-                ...(cp ? { cp } : {}),
-                addGoalSupplement: input.addGoalSupplement,
-            });
-            return 'ok';
-        }
-        catch (e) {
-            const errMsg = e.message ?? String(e);
-            // in-run retry：还有重试额度且未中断 → 重跑同一步（不动 onError）。
-            if (attempt < maxRetries && !ctx.signal?.aborted) {
-                attempt++;
-                const isMaxTurns = isMaxTurnsCutoff(errMsg);
-                const delayBase = isMaxTurns
-                    ? (ctx.maxTurnsRetryDelayMs ?? 0)
-                    : (ctx.retryDelayMs ?? 0);
-                const delayMs = delayBase * attempt;
-                const retryKind = isMaxTurns ? '轮数预算用尽，可续跑截断' : '失败';
-                await state.appendProgress(isMaxTurns
-                    ? `↻ ${step.id}: 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}`
-                    : `↻ ${step.id}: ${retryKind}，重试 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}（${errMsg}）`);
-                yield {
-                    type: 'warning',
-                    message: isMaxTurns
-                        ? `step "${step.id}" 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}…`
-                        : `step "${step.id}" 失败：${errMsg}；${delayMs > 0 ? `${delayMs}ms 后` : ''}重试 ${attempt}/${maxRetries}…`,
-                };
-                yield {
-                    type: 'plugin_progress',
-                    pluginId: WF_PLUGIN_ID,
-                    current: input.index + 1,
-                    max: input.total,
-                    message: isMaxTurns
-                        ? `↻ ${step.id} 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}…`
-                        : `↻ 重试 ${step.id} ${attempt}/${maxRetries}…`,
-                };
-                if (delayMs > 0)
-                    await sleepInterruptible(delayMs, ctx.signal);
-                continue; // 重跑同一步
-            }
-            await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-            // onError:'recover' —— retry 用尽仍失败，交给有界恢复 agent 随机应变把这一步救回来。
-            // 「确定性工作流 × TAOR」的结合点：happy path 走刚性 DAG，撞上预料之外的就地
-            // 降级为 agent 自适应；救回则继续 happy path，救不回才 honest halt。
-            if (step.onError === 'recover') {
-                yield {
-                    type: 'warning',
-                    message: `step "${step.id}" 失败：${errMsg}；尝试自适应恢复…`,
-                };
-                yield {
-                    type: 'plugin_progress',
-                    pluginId: WF_PLUGIN_ID,
-                    current: input.index + 1,
-                    max: input.total,
-                    message: `↻ 恢复 ${step.id}…`,
-                };
-                const rec = yield* runRecovery(step, vars, ctx, errMsg);
-                if (ctx.signal?.aborted) {
-                    yield { type: 'interrupted' };
-                    return 'halted';
-                }
-                // 验证闸门：只有恢复 agent 真正交付（rec.ok）才绑 capture 走下去；
-                // 显式放弃 / 产出不可信（rec.ok=false）则带原因 honest halt，绝不盲绑脏值。
-                if (rec.ok) {
-                    yield* commitStep({
-                        step,
-                        result: rec.value,
-                        kind,
-                        vars,
-                        ctx,
-                        state,
-                        ...(cp ? { cp } : {}),
-                        progressLine: `⚠→✓ ${step.id} recovered`,
-                        addGoalSupplement: input.addGoalSupplement,
-                    });
-                    return 'ok';
-                }
-                const combined = `${errMsg}（自适应恢复未成功：${rec.reason}）`;
-                if (cp)
-                    await state.recordFailure(step.id, combined);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: combined };
-                yield {
-                    type: 'error',
-                    error: `Workflow halted at step "${step.id}": ${combined}`,
-                };
-                return 'halted';
-            }
-            if (step.onError === 'continue') {
-                // 降级时给 capture 变量绑【明确占位文本】而非留空：空串静默内插进下游
-                // prompt（如「已知需求分析：\n\n」）是更大的最小惊讶违例——模型看到
-                // 空段会困惑。占位前缀「（上游步骤 」机器可识别；continue 本就是作者
-                // 显式选择「无此内容也继续」，需要严格闸门的步骤应配 onError:halt 或 assert。
-                if (step.capture) {
-                    const placeholder = `（上游步骤 ${step.id} 失败已降级（onError:continue），无内容——` +
-                        `请基于用户原始目标自行推断。错误：${errMsg.length > 120 ? `${errMsg.slice(0, 120)}…` : errMsg}）`;
-                    for (const varName of Object.values(normalizeCapture(step.capture))) {
-                        vars.setGlobal(varName, placeholder);
-                    }
-                }
-                // 降级此前完全静默（仅 progress.md 有 ✗ 行）——补一条 warning 可见化
-                yield {
-                    type: 'warning',
-                    message: `step "${step.id}" 失败已降级（onError:continue）：${errMsg}`,
-                };
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                return 'degraded';
-            }
-            const finalErrMsg = isMaxTurnsCutoff(errMsg)
-                ? `${errMsg}；重试额度已用尽，请拆分该步骤或提高 maxTurns。`
-                : errMsg;
-            if (cp)
-                await state.recordFailure(step.id, finalErrMsg);
-            yield { type: 'workflow_step_end', id: step.id, ok: false, error: finalErrMsg };
-            yield {
-                type: 'error',
-                error: `Workflow halted at step "${step.id}": ${finalErrMsg}`,
-            };
-            return 'halted';
-        }
-    }
-}