minimal-agent 0.12.0 → 0.14.0

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

@@ -1,513 +1,229 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/types.ts —— workflow runner 核心类型
+ *  plugins/workflow-runner/src/types.ts —— 代码编排引擎的核心类型
  * ------------------------------------------------------------
- *  外层确定性 step 列表驱动执行，LLM 只在 llm: / skill: / agent: 节点出场。
- *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
- *  RunContext）和 UI 事件（WorkflowEvent）。
+ *  V2 只定义 ESM 元数据、宿主上下文和运行时边界；业务控制流由 JavaScript 本身
+ *  表达，Runner 不维护具体步骤类型。
  *
- *  与 src/types.ts 关系：WorkflowEvent 是插件**私有**事件，结构上满足
- *  framework 的 PluginEvent 开放契约（type: string + 任意 payload），
- *  经 plugin.ts -> pluginRunner 原样透传给 UI；UI 不识别即静默忽略。
- *  src/types.ts 的 LoopEvent union **不**包含 workflow_*，框架零插件耦合。
+ *  ⚠️ 这里**没有** name 字段：工作流名恒等于目录名（`workflows/<name>/`）。
+ *  legacy 时代 yaml 里的 `name:` 与文件名是两处真值，实测漂移过（workflow-evolve
+ *  的配置里专门写了「`name` 取 yaml 头部字段，不是文件名」这条注意事项）。
  * ============================================================
  */
 
 import type {
-  ImageDetail,
+  ManagedExecutionBridge,
+  ManagedExecutionContext,
+} from '../../../src/managedExecution/types.js';
+import type {
+  AgentRuntimeContext,
+  ContextBundle,
+  InvocationResource,
+  LlmStreamEvent,
   Message,
   PluginContext,
+  PromptCacheContext,
   Provider,
   SessionState,
   Tool,
   ToolCallContext,
 } from '../../../src/plugin-sdk.js';
 
-// ---------------- 1. Workflow / Step 定义 ----------------
-
-export type InputType = 'string' | 'number' | 'enum';
-
+/** 一个声明的输入参数。形状沿用 legacy，CLI 位置参数映射语义必须保持一致。 */
 export interface InputDef {
   name: string;
-  type: InputType;
+  description?: string;
   required?: boolean;
   default?: unknown;
-  /** type=enum 时必填 */
+  type?: 'string' | 'number' | 'enum' | 'resource';
+  /** MIME globs/extensions accepted by a resource input. */
+  accepts?: string[];
+  /** Resource input may receive files/directories and multiple attachments. */
+  allowFile?: boolean;
+  allowDirectory?: boolean;
+  multiple?: boolean;
+  /** Bind compatible current-turn attachments when no explicit path is given. */
+  attachmentFallback?: boolean;
+  maxItems?: number;
+  /** Task identity basis for resources: stable reference id or content hash. */
+  identity?: 'reference' | 'content';
+  /** Present attached/explicit files to the workflow as a staged directory. */
+  materialize?: 'auto' | 'directory';
+  /** 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）。
+   * 贪婪首参：名后**全部**位置参数空格 join 进它，不逐位拆映射。
+   *
+   * 只许标在第 0 位。存在理由是真实事故：ppt 的 `topic` 不贪婪时，用户打一句
+   * 自然语言会被空格拆碎，第二段位置参数撞上 number 类型的 `pages` 报「必须是数字」。
    */
   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>;
-
+/** `export const meta = {...}` 的形状（执行前静态解析得到）。 */
+export interface WorkflowMeta {
+  /** V2真实ESM工作流契约版本。 */
+  apiVersion: 2;
+  /** Statically declared ordinary child workflows; included in bundle identity. */
+  dependencies?: string[];
+  /** Bare ESM package imports used by this workflow. node: and relative imports need no declaration. */
+  packages?: string[];
+  /** 一句话说明，显示在 /workflows 列表里。必填。 */
+  description: string;
+  inputs?: InputDef[];
   /**
-   * 本步需要宿主的哪类能力（**最小权限，显式声明**）。
-   *
-   * ```yaml
-   * - id: open_app
-   *   tool: ComputerUse
-   *   uses: [computer]
-   * ```
-   *
-   * 引擎只把**声明过的那一片**转发给 `executeTool`：
-   *   · 未声明 → 工具拿不到对应上下文 → 走它自己的清晰报错（ComputerUse 会说
-   *     「当前宿主未启用 Computer Use」），不会静默降级成一个看起来成功的空操作；
-   *   · 声明了但宿主没提供 → runner **响亮报错**，而不是跑到一半才发现。
+   * 声明产物（相对工作目录）。**只是种子** —— 逐迭代产物由运行时的
+   * `declareArtifact(p)` 追加进同一集合。
    *
-   * 为什么不默认全给：工作流是**无人值守**跑的。给一份 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 等不应污染后续上下文的步骤。
+   * 原因：meta 是执行前静态求值的纯字面量，写不出 `out/${session}/page-${i}.png`
+   * 这种带循环下标的路径；而 ppt/illustrate 恰恰是这个形状。只留静态声明会让
+   * new-task 清理漏掉它们，且**表现为静默漏档而不是报错**。
    */
-  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）。
+   * resume 时额外回退的调用数（承接 legacy 的 `self_heal.backoff`）。
+   * 缺省 0。用于「最后一次成功调用可能有未完成副作用」的场景。
    */
-  max_retries?: number;
+  resumeBackoff?: number;
+  /** 可选外层控制器；Runner 只消费其通用执行租约。 */
+  managedRuntime?: string;
 }
 
-export interface WorkflowDef {
+/** 磁盘上发现的一个工作流。 */
+export interface WorkflowScript {
+  /** 工作流名 = 目录名（唯一真值）。 */
   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[];
+  /** 工作流目录绝对路径。 */
+  dir: string;
+  /** `<dir>/workflow.mjs` 绝对路径。 */
+  scriptPath: string;
+  /** 脚本全文（journal 的脚本指纹按它算）。 */
+  source: string;
+  meta: WorkflowMeta;
+  /** meta 字面量之后的位置，仅供静态校验器报告源码位置。 */
+  bodyOffset: number;
 }
 
-// ---------------- 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);
-  }
+/** 发现阶段跳过的坏工作流 —— 静默跳过是不可接受的，必须能报给用户。 */
+export interface WorkflowLoadFailure {
+  name: string;
+  scriptPath: string;
+  errors: string[];
 }
 
-/**
- * 把 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;
+export interface DiscoveryResult {
+  workflows: WorkflowScript[];
+  failures: WorkflowLoadFailure[];
 }
 
-// ---------------- 3. 运行上下文 ----------------
+// ---------------------------------------------------------------------------
+//  运行上下文
+// ---------------------------------------------------------------------------
 
 /**
- * runner 内部传递的运行时上下文。
+ * 一次工作流运行需要的全部宿主上下文。
  *
- * 设计：不让 step executors 直接拿 PluginRunnerOptions，避免把"插件运行机制"
- * 暴露到 workflow 层。RunContext 只暴露 executors 真正需要的东西。
+ * 相对 legacy 的同名类型删掉了 `selfHealMaxRetries` / `retryDelayMs` /
+ * `maxTurnsRetryDelayMs` —— 那三个是 DSL 的 `self_heal:` 声明，代码形态里
+ * 「重试三次、每次退避一点」就是一个 `for` 加 `try`，不需要引擎参与。
  */
 export interface RunContext {
   provider: Provider;
-  runtimeContext?: import('../../../src/plugin-sdk.js').AgentRuntimeContext;
+  runtimeContext?: AgentRuntimeContext;
   signal?: AbortSignal;
   /**
-   * 宿主授权上下文。**按 `StepDef.uses` 切片后**才转给工具，不整份下发。
-   * 切片逻辑在 `stepExecutors/tool.ts::hostContextFor`（单一出处）。
-   */
-  host?: import('../../../src/plugin-sdk.js').PluginContext['host'];
-  /** 当前工作目录（用于 skill/plugin 扫描和文件操作） */
+   * 宿主授权上下文（浏览器 / 电脑操控）。
+   *
+   * ⚠️ **不整份下发给每次调用** —— 由调用点按显式声明切片。一份无人值守的脚本
+   * 隐式拿到全权是危险的，这条从 legacy 原样继承。
+   */
+  host?: PluginContext['host'];
+  /** Host-authorized resources for this invocation; never persisted or published. */
+  inputResources?: readonly InvocationResource[];
+  /** Resources bound to declared input names (the public workflow global). */
+  inputResourceMap?: Record<string, InvocationResource[]>;
+  /** 当前工作目录。注意实际文件操作要走 `effectiveWorkflowCwd`（可能已进 worktree）。 */
   cwd: string;
   /**
-   * 可用工具列表。
-   * agent/llm/skill 与确定性 tool 步都以此列表为宿主授权上限。
-   * plugin.ts 先按 runtime 和父宿主白名单过滤，再把同一列表交给提示词、
-   * Schema 和真实执行，任何工作流节点都不能从 ALL_TOOLS 恢复隐藏能力。
+   * 可用工具列表 —— 宿主授权的上限。
+   *
+   * 提示词、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）。
+   * 共享 TAOR history 引用。
    *
-   * v0.9 起：agent/llm/skill/recover 步通过 runQuery(TAOR) 写入此 history。
-   * v0.9 后：agent/llm/skill 步通过 runQuery 直接写入此 history，
-   * 实现上下文自然积累——workflow 每步执行过程对后续对话完全可见。
+   * agent/llm/skill 调用经 runQuery 直接写进它，上下文自然积累 ——
+   * 工作流每步的执行过程对后续对话完全可见（单一上下文原则）。
    */
   history: Message[];
-  /**
-   * 工作流总目标（= WorkflowDef.description），由 runWorkflow 注入。
-   * 仅 onError:'recover' 的恢复 agent 用，给它「这条工作流到底想干什么」的大局观。
-   */
+  transientContext?: string;
+  transientBundle?: ContextBundle;
+  promptCache?: PromptCacheContext;
+  /** 会话状态：驱动自动压缩，且 `activeWorktree` 决定工具的有效 cwd。 */
+  sessionState?: SessionState;
+  /** 工作流总目标（取自 meta.description 或首个 required 输入）。 */
   goal?: string;
   /**
-   * 通用目标锚定字符串（由 runWorkflow 从 inputs 中自动提取）。
-   *
-   * 设计目的：工作流执行过程中（尤其是多步、长时间、fresh_context 场景），
-   * LLM 可能因上下文膨胀或 history 重置而"忘记"用户的原始目标，导致
-   * 后续步骤偏离方向（舍本逐末）。
-   *
-   * runner 在启动时从 inputs 中提取目标（优先取名为 "goal" 的输入，
-   * 其次取第一个 required string 输入），构建紧凑的锚定字符串。
-   * agent/llm/skill 步骤在构造 prompt 时自动将其前置注入，
-   * 确保**每一步 LLM 都能看到原始目标**，无需每个 YAML 手写 `${goal}`。
+   * 目标锚定串：每次 agent/llm/skill 调用自动前置注入。
    *
-   * 为空时（无 string 类型 inputs / 无法识别目标）executor 自动跳过注入。
+   * 存在理由是真实失效模式：多步长跑（尤其上下文压缩过后），模型会「忘记」
+   * 用户的原始目标而逐渐偏航。锚定由引擎注入，**对脚本作者透明** ——
+   * 作者不需要在每个 prompt 里手写目标。
    */
   goalAnchor?: string;
+  /** 外层运行时分配的通用执行租约；普通工作流不设置。 */
+  managedExecution?: ManagedExecutionContext;
+  /** 外层控制器与 Attempt Executor 之间的窄桥。 */
+  managedBridge?: ManagedExecutionBridge;
+  /** Children may account usage, but never receive the outer lifecycle bridge. */
+  usageRecorder?: ManagedExecutionBridge['recordUsage'];
+  /**
+   * 本次运行的资源账本（`budget()` 的数据源）。
+   *
+   * ⚠️ 有外层控制器时以**它返回的持久化快照**为准，进程内这份只是没有控制器时的兜底：
+   * 断点续跑时账本重放不重新执行 agent/llm，进程内计数会从 0 起，
+   * 而 Goal 侧的 `goal.usage` 是跨进程累计的。
+   * `trustworthy=false` 表示至少有一次调用的 provider 没回报 usage，这份账偏低。
+   */
+  resourceLedger?: {
+    inputTokens: number;
+    outputTokens: number;
+    limit: number | null;
+    trustworthy: boolean;
+  };
   /**
-   * 用户补充要求（贯穿目标的活载体）。来源三类，引擎自动累加：
-   *   1. pause 审批闸门的自由输入（free_text:'approve' 放行 + 非空反馈）
-   *   2. 声明 goal_supplement:true 的步骤产出（如 stage0 澄清问答结论）
-   *   3. 仲裁延续 resume 时的新输入（「继续，但改成 12 页」的修改意见）
-   * 渲染：agentCommon.effectiveGoalAnchor 把它们以「📌 用户补充要求」逐条
-   * 追加在 goalAnchor 之后注入每步 prompt——补充要求与原始目标同等贯穿始终。
-   * 持久化：runner 同步写状态目录 supplements.json，跨进程 resume 不丢。
+   * 用户补充要求，与原始目标**同等贯穿始终**。三个来源，引擎自动累加：
+   *   ① `ask()` 审批闸门里用户的自由输入
+   *   ② 显式调用 `addGoalSupplement()` 的产出（如开头澄清问答的结论）
+   *   ③ 仲裁判为 resume 时用户给的新指令（「继续，但改成 12 页」）
+   * 渲染成「📌 用户补充要求」跟在 goalAnchor 之后。持久化到状态目录，
+   * 跨进程 resume 不丢。
    */
   goalSupplements?: string[];
   /**
-   * DI：chat 实现（仅测试用）。生产不传 → runQuery 用默认 llm/client.ts。
-   * 测试传 stub → 零污染 mock。
+   * 本次运行声明的产物（相对 cwd）。**运行时可增长** —— `meta.artifacts`
+   * 只是种子，循环体里的逐迭代产物经 `declareArtifact()` 加进来。
+   *
+   * 用途：内核 Write/Edit 有「文件已存在必须先 Read」守卫（进程级状态，
+   * 跨进程 resume 必空）。写自家声明产物时引擎自动 pre-Read 解除守卫；
+   * 非声明产物的盲写保护原样生效。
    */
+  declaredArtifacts?: Set<string>;
+  /** DI：chat 实现，仅测试用。生产不传 → runQuery 走默认 llm/client.ts。 */
   chat?: (args: {
-    provider: import('../../../src/plugin-sdk.js').Provider;
-    messages: import('../../../src/plugin-sdk.js').Message[];
-    tools: import('../../../src/plugin-sdk.js').Tool[];
+    provider: Provider;
+    messages: Message[];
+    tools: Tool[];
     signal?: AbortSignal;
-    promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
-  }) => AsyncGenerator<
-    import('../../../src/plugin-sdk.js').LlmStreamEvent,
-    void,
-    undefined
-  >;
-  /**
-   * DI：executeTool 实现（仅测试用）。同上。
-   */
+    promptCache?: PromptCacheContext;
+  }) => AsyncGenerator<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,
@@ -518,85 +234,4 @@ export interface RunContext {
     | '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> };