minimal-agent 0.12.0 → 0.14.0

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

@@ -1,20 +1,45 @@
-import type { ToolCallContext } from '../../../src/plugin-sdk.js';
-import type { RunContext, StepDef } from './types.js';
-
 /**
- * The workflow identity stays anchored to the registered workspace, while file
- * and process tools follow a session worktree as soon as EnterWorktree creates
- * one. Keeping this decision in one helper prevents executors from drifting.
+ * ============================================================
+ *  plugins/workflow-runner/src/toolRuntime.ts —— 工具调用的运行上下文
+ * ------------------------------------------------------------
+ *  宿主能力由每次工具调用的显式 `uses` 数组收敛 ——
+ *  代码形态里没有「step」这个东西，宿主能力由调用点在 `tool()`/`agent()` 的
+ *  选项里显式声明。
+ *
+ *  ⚠️ `effectiveWorkflowCwd` 是**红线级**的单一出处，别在别处再算一次：
+ *  会话可能在运行途中进入 worktree（模型可自主调 EnterWorktree），此后写文件的
+ *  工具跟着 worktree 走。验收侧（verify/exists/readJson）必须用**同一个**函数取 cwd，
+ *  否则就是「产物写进 worktree、验收去原工作区的空目录里找」——条件恒 false，
+ *  引擎反复重试后莫名失败，而产物其实好好躺在 worktree 里。
+ *
+ *  也正因为 worktree 是**运行途中**才进入的，取 cwd 必须在**每次调用时**现算，
+ *  不能在运行开始时快照一次存起来。
+ * ============================================================
  */
+
+import type { ToolCallContext } from '../../../src/plugin-sdk.js';
+import type { RunContext } from './types.js';
+
+/** 宿主能力声明：需要浏览器或电脑操控时由调用点显式列出。 */
+export type HostCapability = 'browser' | 'computer';
+
+/** 当前有效工作目录 —— 进了 worktree 就跟着走。见文件头注的红线说明。 */
 export function effectiveWorkflowCwd(ctx: RunContext): string {
   return ctx.sessionState?.activeWorktree?.path ?? ctx.cwd;
 }
 
+/**
+ * 组装一次工具调用的 ToolCallContext。
+ *
+ * @param uses 本次调用显式声明需要的宿主能力；缺省表示不需要任何授权切片。
+ * @returns 成功返回上下文；宿主没提供所声明的能力时返回 `{ error }`（不抛，
+ *          让调用方把原因当 tool_result 回填给模型）。
+ */
 export function buildWorkflowToolContext(
-  step: StepDef,
   ctx: RunContext,
   toolCallId: string,
   reportProgress: NonNullable<ToolCallContext['reportProgress']>,
+  uses?: HostCapability[],
 ): ToolCallContext | { error: string } {
   const context: ToolCallContext = {
     ...ctx.toolContext,
@@ -33,13 +58,13 @@ export function buildWorkflowToolContext(
     reportProgress,
   };
 
-  for (const capability of step.uses ?? []) {
+  for (const capability of uses ?? []) {
     if (capability === 'computer') {
       if (!ctx.host?.computerRun) {
         return {
           error:
-            'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— ' +
-            '请在支持 Computer Use 的宿主启动，或去掉该步的 uses 声明。',
+            "声明了 uses:['computer']（需要电脑操控能力），但本次运行的宿主没有提供 —— " +
+            '请在支持 Computer Use 的宿主里启动，或去掉该声明。',
         };
       }
       context.computerRun = ctx.host.computerRun;
@@ -53,7 +78,7 @@ export function buildWorkflowToolContext(
       if (!ctx.host?.browserRun) {
         return {
           error:
-            'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。',
+            "声明了 uses:['browser']（需要浏览器授权上下文），但本次运行的宿主没有提供。",
         };
       }
       context.browserRun = ctx.host.browserRun;

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

@@ -1,111 +1,13 @@
 /**
  * ============================================================
- *  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 头部字段，不是文件名」这条注意事项）。
  * ============================================================
  */
-// ---------------- 2. 变量栈（loop scope 用） ----------------
-/**
- * 简单的多帧变量栈：
- *   - 最外层（frame 0）放 inputs + 全局变量
- *   - 进入 loop 时 push() 新帧，存当前迭代的 as / as_idx
- *   - 退出 loop 时 pop()
- *
- * get(key) 从栈顶往下找第一个匹配的 frame，类似 JS 的 lexical scope。
- */
-export class VarStack {
-    frames = [{}];
-    /**
-     * 哪些帧是「循环迭代帧」—— 只为装 `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 存着最后读到的值」，
-     * 而不是「它只在这一轮迭代里活着」。
-     */
-    iterationFrames = new Set();
-    /**
-     * 写一个**作者命名**的变量（capture / set 步 / 引擎内部状态）。
-     *
-     * 穿透所有迭代帧，落到最近的非迭代帧上 —— 这样它在循环结束后依然存在。
-     */
-    set(key, val) {
-        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, val) {
-        this.frames[this.frames.length - 1][key] = val;
-    }
-    /** 写到栈底（root frame），用于 inputs / 全局常量 */
-    setGlobal(key, val) {
-        this.frames[0][key] = val;
-    }
-    get(key) {
-        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) {
-        for (let i = this.frames.length - 1; i >= 0; i--) {
-            if (key in this.frames[i])
-                return true;
-        }
-        return false;
-    }
-    push() {
-        this.frames.push({});
-    }
-    /** 压一个迭代帧：只有 `setIteration` 写进来的东西会随 `pop` 消失。 */
-    pushIteration() {
-        this.frames.push({});
-        this.iterationFrames.add(this.frames.length - 1);
-    }
-    pop() {
-        if (this.frames.length > 1) {
-            this.iterationFrames.delete(this.frames.length - 1);
-            this.frames.pop();
-        }
-    }
-    /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
-    snapshot() {
-        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) {
-    if (cap == null)
-        return {};
-    if (typeof cap === 'string')
-        return { result: cap };
-    return cap;
-}
+export {};