minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/src/types.ts

@@ -0,0 +1,602 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/types.ts —— workflow runner 核心类型
+ * ------------------------------------------------------------
+ *  外层确定性 step 列表驱动执行，LLM 只在 llm: / skill: / agent: 节点出场。
+ *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
+ *  RunContext）和 UI 事件（WorkflowEvent）。
+ *
+ *  与 src/types.ts 关系：WorkflowEvent 是插件**私有**事件，结构上满足
+ *  framework 的 PluginEvent 开放契约（type: string + 任意 payload），
+ *  经 plugin.ts -> pluginRunner 原样透传给 UI；UI 不识别即静默忽略。
+ *  src/types.ts 的 LoopEvent union **不**包含 workflow_*，框架零插件耦合。
+ * ============================================================
+ */
+
+import type {
+  ImageDetail,
+  Message,
+  PluginContext,
+  Provider,
+  SessionState,
+  Tool,
+  ToolCallContext,
+} from '../../../src/plugin-sdk.js';
+
+// ---------------- 1. Workflow / Step 定义 ----------------
+
+export type InputType = 'string' | 'number' | 'enum';
+
+export interface InputDef {
+  name: string;
+  type: InputType;
+  required?: boolean;
+  default?: unknown;
+  /** type=enum 时必填 */
+  values?: string[];
+  description?: string;
+  /**
+   * 贪婪首参（只许标在 inputs[0]）：命令行里名称之后的【全部】位置参数用空格 join
+   * 成整句写进这个 input，不再逐位 posN↔inputs[N] 映射。让用户「打一句话自然语言」
+   * 即可（句子里的空格不会被拆碎、也不会撞上后面的 number/enum 输入）。其余 input
+   * 只接受 --input k=v。无 greedy 时保持严格 1:1 映射（见 index.ts::runWorkflowFromCommand）。
+   */
+  greedy?: boolean;
+}
+
+export type StepKind =
+  | 'tool'
+  | 'llm'
+  | 'skill'
+  | 'agent'
+  | 'assert'
+  | 'verify'
+  | 'set'
+  | 'branch'
+  | 'loop'
+  | 'break'
+  | 'continue'
+  | 'echo'
+  | 'pause';
+
+export type WorkflowImageInput =
+  | string
+  | {
+      source: string;
+      detail?: ImageDetail;
+      max_long_side_pixel?: number;
+    };
+
+export type StepHistoryMode = 'shared' | 'isolated';
+
+/**
+ * StepDef 是 YAML 里 steps[] 元素直接反序列化的形态。
+ *
+ * 动作字段五选一（互斥优先级 type > tool > skill > agent > llm）：
+ *   - tool:  调原子工具
+ *   - skill: 跑一个外部 SKILL.md 定义的完整 agent（runQuery）
+ *   - agent: 跑一个 inline 描述的有界 TAOR agent（runQuery/TAOR）—— 受工作流指导的随机应变
+ *   - llm:   单轮 LLM 生成（不开工具）
+ *   - type:  控制流（assert / branch / loop / pause / …）
+ *
+ * 其它字段按 step 类型选择性使用，未用到的字段静默忽略。
+ */
+/**
+ * 宿主能力类别 —— `StepDef.uses` 的取值域。
+ *
+ * 刻意按**能力**分类（浏览器 / 电脑）而不是按工具名：同一类能力可能对应多个工具，
+ * 而 yaml 作者关心的是「这一步会不会碰我的机器」，不是工具叫什么。
+ */
+export type HostCapability = 'browser' | 'computer';
+
+export interface StepDef {
+  id: string;
+  tool?: string;
+  skill?: string;
+  llm?: string;
+  /**
+   * inline 开放任务，交给 TAOR 引擎（runQuery）随机应变完成；
+   * 与 tool/llm/skill/type 互斥。支持 ${var} 插值。复用 allowed_tools（缺省全量工具）/
+   * maxTurns（默认 25）/ output_schema / context_files / capture / onError。
+   */
+  agent?: string;
+  type?:
+    | 'assert'
+    | 'verify'
+    | 'set'
+    | 'branch'
+    | 'loop'
+    | 'break'
+    | 'continue'
+    | 'echo'
+    | 'pause';
+
+  /**
+   * type=set 时必填：确定性变量赋值 { 变量名: 值 }，值支持 ${} 插值（deep）。
+   * 设计动机：曾有 yaml 用 `llm: "PLAN"` 当赋值语句——那是真把 "PLAN" 发给模型、
+   * capture 模型的自由回复，变量值非确定。状态机类工作流（ralph-loop 的 phase）
+   * 必须用 set 确定性赋值，llm 步只用于真需要模型产文本的场合。
+   */
+  set?: Record<string, unknown>;
+
+  /**
+   * 本步需要宿主的哪类能力（**最小权限，显式声明**）。
+   *
+   * ```yaml
+   * - id: open_app
+   *   tool: ComputerUse
+   *   uses: [computer]
+   * ```
+   *
+   * 引擎只把**声明过的那一片**转发给 `executeTool`：
+   *   · 未声明 → 工具拿不到对应上下文 → 走它自己的清晰报错（ComputerUse 会说
+   *     「当前宿主未启用 Computer Use」），不会静默降级成一个看起来成功的空操作；
+   *   · 声明了但宿主没提供 → runner **响亮报错**，而不是跑到一半才发现。
+   *
+   * 为什么不默认全给：工作流是**无人值守**跑的。给一份 yaml 隐式的完整机器控制权，
+   * 等于让任何人写的脚本都能在没人看着的时候点任何东西。显式声明还有个副作用是
+   * 好的 —— yaml 自文档化，读一眼就知道哪些步会碰这台机器。
+   */
+  uses?: HostCapability[];
+
+  args?: Record<string, unknown>;
+  input?: string;
+  capture?: Record<string, string>;
+  when?: string;
+  onError?: 'halt' | 'continue' | 'recover';
+  /**
+   * onError:'recover' 时给恢复 agent 的作者提示（可选，支持 ${var} 插值）。
+   * 例如 "端口被占就换 3001 重试" / "先 Read 现有文件再决定怎么改"。
+   */
+  recover_hint?: string;
+  maxTurns?: number;
+  /**
+   * 多模态图片输入，仅 llm / agent 节点生效。字符串表示图片路径/URL；
+   * 对象形式可覆盖单张图片的 detail / max_long_side_pixel。路径支持 ${} 插值。
+   */
+  images?: WorkflowImageInput[];
+  /** 是否解析 prompt 文本中的 @./image.png 或图片 URL，仅 llm / agent 节点生效。 */
+  parse_inline_images?: boolean;
+  /** 本步骤图片 detail 默认值，单张 images[].detail 可覆盖。 */
+  image_detail?: ImageDetail;
+  /** 本步骤图片最长边默认值，单张 images[].max_long_side_pixel 可覆盖。 */
+  image_max_long_side_pixel?: number;
+
+  /**
+   * llm / agent / skill 步的历史使用方式。
+   * - shared: 默认，沿用共享 TAOR history，步骤消息会继续留给后续步骤。
+   * - isolated: 只带系统提示和当前 step prompt 执行，结果经 capture/文件传递，
+   *   不把本步 user/assistant/image 消息写回共享 history。适合多模态验图、
+   *   敏感图片复核、长导出 agent 等不应污染后续上下文的步骤。
+   */
+  history_mode?: StepHistoryMode;
+
+  condition?: string;
+
+  /** type=verify 时必填：检查项列表（YAML 数组或逗号分隔字符串），每项格式 "type:value"（如 "file_exists:./PLAN.md"） */
+  checks?: string[] | string;
+
+  onFail?: string;
+  then?: StepDef[];
+  else?: StepDef[];
+  over?: string;
+  as?: string;
+  do?: StepDef[];
+
+  /** type=loop while 模式：最大迭代次数（安全阀，必填）。无 over 时进入 while 循环。
+   *  支持 ${} 模板字符串（如 "${inputs.max_iterations}"），runner 插值后 coerce 成数字；
+   *  插值结果非正数时**响亮报错**（曾有字符串直接参与 < 比较 → NaN → 静默 0 次迭代的事故）。 */
+  max_iterations?: number | string;
+  /**
+   * type=loop while 模式：每轮迭代前是否重置 history 到循环入口快照（fresh context）。
+   * 默认 false。适用于"同一目标反复执行直到完成"的场景（如 ralph-loop），
+   * 避免历史无限膨胀导致上下文窗口溢出。
+   */
+  fresh_context?: boolean;
+
+  prompt?: string;
+
+  /**
+   * type=pause 时，用户选择「其他」并输入自由文本的处理方式：
+   *   - halt: 默认，视为补充指示/修改要求，不放行
+   *   - approve: 视为带补充要求的放行，可配 capture: { text: varName } 传给后续步骤
+   */
+  free_text?: 'halt' | 'approve';
+
+  /**
+   * type=break / type=continue 的目标循环 id（标签语义）。
+   * 缺省 = 最近一层循环；指定后信号会穿透中间层循环向上传播，直到 id 匹配的
+   * loop 消费它（如审批反馈是方向性变化时，从审批小循环里 continue 到外层
+   * plan_loop 重启整轮规划）。目标 id 不存在时信号冒泡到顶层按正常完成处理。
+   */
+  target?: string;
+
+  /**
+   * type=echo 时必填：确定性输出一段话给用户（支持 ${} 插值），不烧 LLM。
+   * 设计动机：工作流末尾的「完成报告」此前只能用 llm 步复述（多一次调用且可能
+   * 幻觉）；产物/裁决已在变量里时，echo 直接插值输出即可。
+   */
+  message?: string;
+
+  /**
+   * 动作步（tool/llm/skill/agent）与 pause 可选：本步成功后把产出文本作为
+   * 「用户补充要求」追加进 RunContext.goalSupplements，随目标锚定注入后续每一步
+   * （如 stage0 澄清问答的结论应贯穿整条工作流）。引擎自动截断保持锚紧凑。
+   */
+  goal_supplement?: boolean;
+
+  /**
+   * 任意步可选：人话进度显示名（支持 ${} 插值）。声明后该步在状态行显示这段
+   * 文案（如「阶段2/6·起草实现计划」），**不再附块内相对序号**——嵌套块的
+   * i/total（顶层 5、循环体 12…）对用户是噪声，阶段语言才是真正的进度。
+   * 未声明的步保持 legacy 格式（i/total step <id> (<kind>)）。
+   */
+  title?: string;
+
+  /** ADR-05: LLM 输出 JSON Schema 强约束，走 provider-native structured output；仅 llm 节点生效（skill 节点 loader 拒绝）。 */
+  output_schema?: Record<string, unknown>;
+
+  /** ADR-05: 仅 llm 节点声明的上下文文件清单（skill 节点 loader 拒绝）；runner 拼 path+hint 进 prompt 并开放 Read 子循环，不 inline 内容。 */
+  context_files?: Array<{ path: string; hint?: string }>;
+
+  /** ADR-05: agent 节点的工具白名单；未声明时继承宿主过滤后的有效工具集。 */
+  allowed_tools?: string[];
+
+  /**
+   * 仅 agent 节点可选：确定性完成条件（白名单表达式，如 fileExists('./out/x.pptx')）。
+   * 步结束后求值；不满足时引擎自动 nudge 同一 agent 在共享 history 上继续执行
+   * （上限 2 次），仍不满足按可重试失败交给 onError/max_retries。
+   * 动机：弱模型 announce-not-do 烂尾兜底——对抗逻辑收回引擎单点，yaml 不再写
+   * 「每条消息必须含工具调用」这类 prompt 规则。
+   */
+  done_when?: string;
+
+  // ---- 断点续执行 / 自愈（Phase 1）----
+
+  /** 此步骤产出的文件路径列表（相对 cwd，用于产物生命周期管理） */
+  artifacts?: string[];
+
+  /**
+   * 自愈：此步骤失败时的额外 in-run 重试次数（总尝试 = 1 + max_retries）。
+   * 缺省继承 WorkflowDef.self_heal.max_retries（经 RunContext.selfHealMaxRetries）。
+   * runner 已实装：失败先确定性重跑同一步，retry 用尽才落 onError（recover/continue/halt）。
+   */
+  max_retries?: number;
+}
+
+export interface WorkflowDef {
+  name: string;
+  description: string;
+  version?: string;
+  inputs?: InputDef[];
+  steps: StepDef[];
+  /** 编辑器布局信息；runner 严格忽略 */
+  __meta?: unknown;
+  /** loader 写入：yaml 来源（cwd / packageRoot），便于排错 */
+  __source?: string;
+
+  // ---- 断点续执行 / 自愈（Phase 1）----
+
+  /**
+   * 全局自愈配置（runner 已实装两条机制）：
+   *   - max_retries：单步 **in-run** 失败重试（同一次运行内确定性重跑同一步）。
+   *   - backoff：    **跨次** 重跑（同任务中断后再次 /workflow）时，从「已完成步 - backoff」处恢复。
+   *
+   * checkpoint / resume 范围：顶层 steps[] 全量 + **顶层 loop 的 do[] 一层**
+   * （复合 checkpoint「loopId@@迭代号@@stepId」，resume 可恢复到迭代中间，
+   * 见 workflowState.ts）。更深嵌套（loop 内的 loop 的 do[] / branch.then[]）
+   * 仍作为原子单元；resume 只回放 VarStack 变量、不恢复 TAOR history。
+   */
+  self_heal?: {
+    /** 跨次重跑的回退步数（默认 1 = 从最后一个已完成步重跑；设 2 则再往前一步）。 */
+    backoff?: number;
+    /** 单步额外 in-run 重试次数（默认 0 = 不重试；总尝试 = 1 + max_retries）。 */
+    max_retries?: number;
+    /**
+     * in-run 重试前的退避等待（毫秒，线性：第 n 次重试等 n × retry_delay_ms）。
+     * 默认 0 = 立即重跑。瞬态故障（网络抖动/限流/provider 短暂 5xx）下立即重跑
+     * 大概率撞同一个故障窗口，配 2000-5000 给故障留恢复时间。
+     */
+    retry_delay_ms?: number;
+    /**
+     * maxTurns 截断重试前的退避等待（毫秒，线性：第 n 次重试等 n × max_turns_retry_delay_ms）。
+     * 默认 0 = 保持旧行为立即续跑；PPT/长文档类高峰期工作流可单独配置，避免模型端拥塞时
+     * 连续撞顶刷屏，同时让 UI 明确这是“可重试截断”而不是最终失败。
+     */
+    max_turns_retry_delay_ms?: number;
+  };
+
+  /** 工作流级声明式产物列表（runner 用于新任务检测时的清理 / 归档时的追踪）。
+   *  路径相对于 cwd（getWorkingDir）。step 级 artifacts 是子集。 */
+  artifacts?: string[];
+}
+
+// ---------------- 2. 变量栈（loop scope 用） ----------------
+
+/**
+ * 简单的多帧变量栈：
+ *   - 最外层（frame 0）放 inputs + 全局变量
+ *   - 进入 loop 时 push() 新帧，存当前迭代的 as / as_idx
+ *   - 退出 loop 时 pop()
+ *
+ * get(key) 从栈顶往下找第一个匹配的 frame，类似 JS 的 lexical scope。
+ */
+export class VarStack {
+  private frames: Record<string, unknown>[] = [{}];
+  /**
+   * 哪些帧是「循环迭代帧」—— 只为装 `as` / `as_idx` 这类**每轮重置**的迭代变量而生。
+   *
+   * ⚠️ 区分这个的原因是一个真实 bug：loop 每轮 `push()`…`pop()`，于是循环体里
+   * `capture` 出来的变量**随迭代帧一起被弹掉**，循环一结束就没了。
+   * 实测代价：seek 循环一路把书翻到第 12 页、`cur_page` 明明是「PAGE=12 13」，
+   * 循环外的 `guard_landing` 读到的却是空串，于是报「没能翻到第 12 页（最后读到的
+   * 页码：）」—— 一个刚刚成功的任务被判成失败，而且报错文案完全指不向真因。
+   *
+   * 正确的语义分界：**迭代变量按帧作用域，作者显式命名的变量不按**。
+   * yaml 作者写 `capture: { text: cur_page }` 时期待的是「cur_page 存着最后读到的值」，
+   * 而不是「它只在这一轮迭代里活着」。
+   */
+  private iterationFrames = new Set<number>();
+
+  /**
+   * 写一个**作者命名**的变量（capture / set 步 / 引擎内部状态）。
+   *
+   * 穿透所有迭代帧，落到最近的非迭代帧上 —— 这样它在循环结束后依然存在。
+   */
+  set(key: string, val: unknown): void {
+    for (let i = this.frames.length - 1; i >= 0; i--) {
+      if (!this.iterationFrames.has(i)) {
+        this.frames[i][key] = val;
+        return;
+      }
+    }
+    this.frames[0][key] = val;
+  }
+
+  /** 写一个**迭代变量**（`as` / `as_idx`）：落在当前迭代帧，随 pop 一起消失。 */
+  setIteration(key: string, val: unknown): void {
+    this.frames[this.frames.length - 1][key] = val;
+  }
+
+  /** 写到栈底（root frame），用于 inputs / 全局常量 */
+  setGlobal(key: string, val: unknown): void {
+    this.frames[0][key] = val;
+  }
+
+  get(key: string): unknown {
+    for (let i = this.frames.length - 1; i >= 0; i--) {
+      if (key in this.frames[i]) return this.frames[i][key];
+    }
+    return undefined;
+  }
+
+  has(key: string): boolean {
+    for (let i = this.frames.length - 1; i >= 0; i--) {
+      if (key in this.frames[i]) return true;
+    }
+    return false;
+  }
+
+  push(): void {
+    this.frames.push({});
+  }
+
+  /** 压一个迭代帧：只有 `setIteration` 写进来的东西会随 `pop` 消失。 */
+  pushIteration(): void {
+    this.frames.push({});
+    this.iterationFrames.add(this.frames.length - 1);
+  }
+
+  pop(): void {
+    if (this.frames.length > 1) {
+      this.iterationFrames.delete(this.frames.length - 1);
+      this.frames.pop();
+    }
+  }
+
+  /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
+  snapshot(): Record<string, unknown> {
+    return Object.assign({}, ...this.frames);
+  }
+}
+
+/**
+ * 把 yaml 的 capture 归一化成 { resultField: varName } map。支持两种写法
+ * （通用 DSL，根治「裸字符串 capture 被 Object.entries/values 迭代成单字符」的静默 footgun）：
+ *   - map 形式：   capture: { text: foo, args.content: bar }
+ *   - 简写字符串： capture: foo  ≡  capture: { result: foo }
+ *     绑 StepResult.raw.result —— llm/agent=文本、tool=回执，各 executor 都提供 result 别名。
+ *
+ * 放在 types.ts（零依赖）供 runner.ts（bindCapture）与 agentCommon.ts（describeCaptureContract）
+ * 共用，避免 runner↔agentCommon 循环引用。
+ */
+export function normalizeCapture(
+  cap: Record<string, string> | string | undefined,
+): Record<string, string> {
+  if (cap == null) return {};
+  if (typeof cap === 'string') return { result: cap };
+  return cap;
+}
+
+// ---------------- 3. 运行上下文 ----------------
+
+/**
+ * runner 内部传递的运行时上下文。
+ *
+ * 设计：不让 step executors 直接拿 PluginRunnerOptions，避免把"插件运行机制"
+ * 暴露到 workflow 层。RunContext 只暴露 executors 真正需要的东西。
+ */
+export interface RunContext {
+  provider: Provider;
+  runtimeContext?: import('../../../src/plugin-sdk.js').AgentRuntimeContext;
+  signal?: AbortSignal;
+  /**
+   * 宿主授权上下文。**按 `StepDef.uses` 切片后**才转给工具，不整份下发。
+   * 切片逻辑在 `stepExecutors/tool.ts::hostContextFor`（单一出处）。
+   */
+  host?: import('../../../src/plugin-sdk.js').PluginContext['host'];
+  /** 当前工作目录（用于 skill/plugin 扫描和文件操作） */
+  cwd: string;
+  /**
+   * 可用工具列表。
+   * agent/llm/skill 与确定性 tool 步都以此列表为宿主授权上限。
+   * plugin.ts 先按 runtime 和父宿主白名单过滤，再把同一列表交给提示词、
+   * Schema 和真实执行，任何工作流节点都不能从 ALL_TOOLS 恢复隐藏能力。
+   */
+  tools: Tool[];
+  transientContext?: string;
+  transientBundle?: import('../../../src/plugin-sdk.js').ContextBundle;
+  promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
+  /**
+   * 共享 TAOR history 引用（来自 pluginRunner.runWithPlugins 的 baseHistory）。
+   *
+   * v0.9 起：agent/llm/skill/recover 步通过 runQuery(TAOR) 写入此 history。
+   * v0.9 后：agent/llm/skill 步通过 runQuery 直接写入此 history，
+   * 实现上下文自然积累——workflow 每步执行过程对后续对话完全可见。
+   */
+  history: Message[];
+  /**
+   * 工作流总目标（= WorkflowDef.description），由 runWorkflow 注入。
+   * 仅 onError:'recover' 的恢复 agent 用，给它「这条工作流到底想干什么」的大局观。
+   */
+  goal?: string;
+  /**
+   * 通用目标锚定字符串（由 runWorkflow 从 inputs 中自动提取）。
+   *
+   * 设计目的：工作流执行过程中（尤其是多步、长时间、fresh_context 场景），
+   * LLM 可能因上下文膨胀或 history 重置而"忘记"用户的原始目标，导致
+   * 后续步骤偏离方向（舍本逐末）。
+   *
+   * runner 在启动时从 inputs 中提取目标（优先取名为 "goal" 的输入，
+   * 其次取第一个 required string 输入），构建紧凑的锚定字符串。
+   * agent/llm/skill 步骤在构造 prompt 时自动将其前置注入，
+   * 确保**每一步 LLM 都能看到原始目标**，无需每个 YAML 手写 `${goal}`。
+   *
+   * 为空时（无 string 类型 inputs / 无法识别目标）executor 自动跳过注入。
+   */
+  goalAnchor?: string;
+  /**
+   * 用户补充要求（贯穿目标的活载体）。来源三类，引擎自动累加：
+   *   1. pause 审批闸门的自由输入（free_text:'approve' 放行 + 非空反馈）
+   *   2. 声明 goal_supplement:true 的步骤产出（如 stage0 澄清问答结论）
+   *   3. 仲裁延续 resume 时的新输入（「继续，但改成 12 页」的修改意见）
+   * 渲染：agentCommon.effectiveGoalAnchor 把它们以「📌 用户补充要求」逐条
+   * 追加在 goalAnchor 之后注入每步 prompt——补充要求与原始目标同等贯穿始终。
+   * 持久化：runner 同步写状态目录 supplements.json，跨进程 resume 不丢。
+   */
+  goalSupplements?: string[];
+  /**
+   * DI：chat 实现（仅测试用）。生产不传 → runQuery 用默认 llm/client.ts。
+   * 测试传 stub → 零污染 mock。
+   */
+  chat?: (args: {
+    provider: import('../../../src/plugin-sdk.js').Provider;
+    messages: import('../../../src/plugin-sdk.js').Message[];
+    tools: import('../../../src/plugin-sdk.js').Tool[];
+    signal?: AbortSignal;
+    promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
+  }) => AsyncGenerator<
+    import('../../../src/plugin-sdk.js').LlmStreamEvent,
+    void,
+    undefined
+  >;
+  /**
+   * DI：executeTool 实现（仅测试用）。同上。
+   */
+  executeTool?: PluginContext['executeTool'];
+  /**
+   * Canonical non-model-visible context shared by deterministic tool nodes.
+   * Browser/computer capabilities are deliberately excluded here and are only
+   * added by the step-level `uses` slicer.
+   */
+  toolContext?: Omit<
+    ToolCallContext,
+    | 'browserRun'
+    | 'computerRun'
+    | 'computerIntervention'
+    | 'reportProgress'
+    | 'toolCallId'
+    | 'cwd'
+  >;
+  /**
+   * 会话状态（驱动 microCompact / reactiveCompact）。
+   *
+   * v0.9.3：从 pluginRunner 透传过来，在 agent/llm/skill 步调用 runQuery 时
+   * 一并传入，确保 workflow 执行期间上下文压缩正常工作（不再只增不减）。
+   */
+  sessionState?: SessionState;
+  /**
+   * self_heal 全局默认重试次数（= WorkflowDef.self_heal.max_retries），由 runWorkflow 注入。
+   * runner 普通动作 step 失败时据此做 in-run retry；step.max_retries 优先于此默认。
+   */
+  selfHealMaxRetries?: number;
+  /** in-run 重试退避基数（= WorkflowDef.self_heal.retry_delay_ms），默认 0 立即重跑。 */
+  retryDelayMs?: number;
+  /** maxTurns 截断重试退避基数（= WorkflowDef.self_heal.max_turns_retry_delay_ms），默认 0 立即续跑。 */
+  maxTurnsRetryDelayMs?: number;
+  /**
+   * 工作流【声明】的产物路径（def.artifacts + 所有 step.artifacts，相对 cwd），
+   * 由 runWorkflow 经 collectDeclaredArtifacts 注入。
+   *
+   * 用途（tool 步覆盖判定）：内核 Write/Edit 工具有「文件已存在必须先 Read」守卫
+   * （进程级状态，跨进程/resume 必空）。确定性 tool 步写的目标若是**声明产物**
+   * （= 工作流自己拥有、本就要覆盖的文件），执行前自动 pre-Read 解除守卫；
+   * 非声明产物的盲写保护原样生效。
+   */
+  declaredArtifacts?: string[];
+}
+
+// ---------------- 4. step 执行结果 ----------------
+
+/**
+ * 每个 step executor 的返回。capture 字段会从 raw 上按 capture map 取值。
+ *
+ *   - raw: 完整结构化结果，给 capture 用
+ *   - preview: 给 UI 展示的短摘要（≤200 char）
+ */
+export interface StepResult {
+  raw: Record<string, unknown>;
+  preview: string;
+  /**
+   * 本步**引入的变量**，resume 跳过它时必须回放这些值。
+   *
+   * ⚠️ 与 `capture` 是两回事，别合并：
+   *   · `capture` 是**作者显式声明**「把产出的哪个字段绑到哪个变量」
+   *   · `replayVars` 是**这一步本身就在写变量**（目前只有 `set`）——
+   *     它没有也不需要 `capture`，但 resume 跳过它时那些变量必须还在
+   *
+   * 实测代价：重构时把 set 的 checkpoint 统一成 `collectCaptured(...)`，
+   * 而 set 步没有 `capture:` → 记成 `{}` → resume 后下游 `phase == "PLAN"`
+   * 断言直接判假。`engineRobustness.test.ts` 抓住了它。
+   */
+  replayVars?: Record<string, unknown>;
+}
+
+// ---------------- 5. workflow 事件（独立类型，便于 step executors 直接 yield） ----------------
+
+export type WorkflowEvent =
+  | { type: 'workflow_start'; name: string; totalSteps: number }
+  | {
+      type: 'workflow_step_start';
+      id: string;
+      kind: StepKind;
+      index: number;
+      total: number;
+      /**
+       * 已插值的人话进度名（step.title）。声明了 title 的步骤带此字段，UI 的
+       * scrollback 进度行显示它、不再显示块内相对序号（嵌套块的 i/total 各自相对
+       * 当前 block，跨层拼在一起会被误读成"跳步"——状态行早已只显示 title，
+       * 此前 scrollback 却仍发 legacy 序号格式，两处不一致即用户看到的"残留"）。
+       * 未声明 title 的步骤省略此字段，UI 回落 legacy "i/total id (kind)"。
+       */
+      title?: string;
+    }
+  | {
+      type: 'workflow_step_end';
+      id: string;
+      ok: boolean;
+      output?: string;
+      error?: string;
+    }
+  | { type: 'workflow_step_skipped'; id: string; reason: string }
+  | { type: 'workflow_done'; name: string; vars: Record<string, unknown> };