minimal-agent 0.13.0 → 0.15.0

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

@@ -1,12 +1,33 @@
 /**
- * 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 必须在**每次调用时**现算，
+ *  不能在运行开始时快照一次存起来。
+ * ============================================================
  */
+/** 当前有效工作目录 —— 进了 worktree 就跟着走。见文件头注的红线说明。 */
 export function effectiveWorkflowCwd(ctx) {
     return ctx.sessionState?.activeWorktree?.path ?? ctx.cwd;
 }
-export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress) {
+/**
+ * 组装一次工具调用的 ToolCallContext。
+ *
+ * @param uses 本次调用显式声明需要的宿主能力；缺省表示不需要任何授权切片。
+ * @returns 成功返回上下文；宿主没提供所声明的能力时返回 `{ error }`（不抛，
+ *          让调用方把原因当 tool_result 回填给模型）。
+ */
+export function buildWorkflowToolContext(ctx, toolCallId, reportProgress, uses) {
     const context = {
         ...ctx.toolContext,
         history: ctx.history,
@@ -21,12 +42,12 @@ export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress)
         toolCallId,
         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 声明。',
+                    error: "声明了 uses:['computer']（需要电脑操控能力），但本次运行的宿主没有提供 —— " +
+                        '请在支持 Computer Use 的宿主里启动，或去掉该声明。',
                 };
             }
             context.computerRun = ctx.host.computerRun;
@@ -38,7 +59,7 @@ export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress)
         if (capability === 'browser') {
             if (!ctx.host?.browserRun) {
                 return {
-                    error: 'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。',
+                    error: "声明了 uses:['browser']（需要浏览器授权上下文），但本次运行的宿主没有提供。",
                 };
             }
             context.browserRun = ctx.host.browserRun;

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,217 +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 头部字段，不是文件名」这条注意事项）。
  * ============================================================
  */
-import { resolve, sep } from 'node:path';
-// ---------------- 2. 变量栈（loop scope 用） ----------------
-/**
- * 简单的多帧变量栈：
- *   - 最外层（frame 0）放 inputs + 全局变量
- *   - 进入 loop 时 push() 新帧，存当前迭代的 as / as_idx
- *   - 退出 loop 时 pop()
- *
- * get(key) 从栈顶往下找第一个匹配的 frame，类似 JS 的 lexical scope。
- *
- * ════════════════ 原型污染防护（v2） ════════════════
- *  三层防线，任何一层破了都还有下一层兜底：
- *  ① 所有 frame 对象用 `Object.create(null)` 创建 → 根本没有原型访问器，
- *     obj["__proto__"] = {...} 不会触发 setter（因为 Object.create(null)
- *     的 [[Prototype]] 是 null，没有 Object.prototype.__proto__ 那个 getter/
- *     setter），只会写成 own property。
- *  ② set* 写入口统一过滤 DANGEROUS_KEYS（`__proto__/constructor/prototype`）
- *     → 即使将来有人改回普通 {} 对象，写操作也到不了原型。
- *  ③ 读侧（expressions 点路径访问）另有 S1 黑名防护（parsePrimary L451），
- *     即使值真写进去了也读不出来。
- * ════════════════════════════════════════════════════
- */
-export class VarStack {
-    frames = [Object.create(null)];
-    /**
-     * 哪些帧是「循环迭代帧」—— 只为装 `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();
-    /**
-     * 本次运行「当前有效工作目录」的解析器，供 fileExists / readJson 这类**读磁盘**的
-     * 内置函数取锚点用。不是 yaml 变量（不进 frames，`${cwd}` 取不到它）。
-     *
-     * ⚠️ 存的是**函数**不是字符串：worktree 是运行途中才进入的（模型调 EnterWorktree），
-     * 创建 VarStack 时固定成字符串的话，之后所有 done_when 仍会锚在旧目录上。
-     * 未设置时由调用方回落 getWorkingDir()。
-     */
-    resolveCwd;
-    /**
-     * 写一个**作者命名**的变量（capture / set 步 / 引擎内部状态）。
-     *
-     * 穿透所有迭代帧，落到最近的非迭代帧上 —— 这样它在循环结束后依然存在。
-     * 危险键（__proto__/constructor/prototype）直接忽略（防线②）。
-     */
-    set(key, val) {
-        if (DANGEROUS_KEYS.has(key))
-            return;
-        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) {
-        if (DANGEROUS_KEYS.has(key))
-            return;
-        this.frames[this.frames.length - 1][key] = val;
-    }
-    /** 写到栈底（root frame），用于 inputs / 全局常量。危险键直接忽略（防线②）。 */
-    setGlobal(key, val) {
-        if (DANGEROUS_KEYS.has(key))
-            return;
-        this.frames[0][key] = val;
-    }
-    get(key) {
-        // 读侧也过危险键：防止 Object.create(null) 上若后续被别的代码写入了 own property
-        // 形式的 __proto__，读出来再被其他地方当对象 key 造成二次污染。
-        if (DANGEROUS_KEYS.has(key))
-            return undefined;
-        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) {
-        if (DANGEROUS_KEYS.has(key))
-            return false;
-        for (let i = this.frames.length - 1; i >= 0; i--) {
-            if (key in this.frames[i])
-                return true;
-        }
-        return false;
-    }
-    push() {
-        this.frames.push(Object.create(null));
-    }
-    /** 压一个迭代帧：只有 `setIteration` 写进来的东西会随 `pop` 消失。 */
-    pushIteration() {
-        this.frames.push(Object.create(null));
-        this.iterationFrames.add(this.frames.length - 1);
-    }
-    pop() {
-        if (this.frames.length > 1) {
-            this.iterationFrames.delete(this.frames.length - 1);
-            this.frames.pop();
-        }
-    }
-    /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件。
-     *  危险键不进入快照（双重保险：帧是 Object.create(null)，读的时候也过不了 get）。*/
-    snapshot() {
-        const out = {};
-        for (const frame of this.frames) {
-            for (const k of Object.keys(frame)) {
-                if (DANGEROUS_KEYS.has(k))
-                    continue;
-                out[k] = frame[k];
-            }
-        }
-        return out;
-    }
-}
-/**
- * 把 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;
-}
-// ---------------- 6. 路径安全守卫（declaredArtifacts / 表达式层共用） ----------------
-/**
- * 规范化 + cwd 范围校验的产物路径。
- *
- * 安全背景：declaredArtifacts 来自 YAML 定义，若作者写 "../../.ssh/id_rsa"，
- * path.join(workingDir, p) 会跟随 ../ 跳出工作目录，new-task 清理时就可能
- * 删掉工作目录外的文件（唯一能造成真实数据损失的入口）。
- *
- * 行为：
- *   - 先用 resolve(workingDir, rawPath) 得到绝对路径（自动归一化 ../）
- *   - 再检查它是否严格在 resolve(workingDir) 目录树之内
- *   - 命中：返回【相对 workingDir 的规范化相对路径】（./ 前缀去除、\\→/），
- *     保证后续 join(workingDir, result) 一定不会越界
- *   - 越界/空串/解析失败：返回 null，调用方应跳过（fail-closed）
- *
- * 跨平台：win32 上 compare 前双方都 normalizeCase（lowercase），其他平台保持大小写敏感。
- */
-export function safeArtifactPath(workingDir, rawPath) {
-    if (!rawPath || typeof rawPath !== 'string')
-        return null;
-    const base = resolve(workingDir);
-    // 必须加路径分隔符作为前缀匹配边界：防止 base=/repo 匹配到 /repo-hack/evil
-    const baseWithSep = base.endsWith(sep) ? base : base + sep;
-    let abs;
-    try {
-        abs = resolve(workingDir, rawPath);
-    }
-    catch {
-        return null;
-    }
-    const sameCase = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
-    const nAbs = sameCase(abs);
-    const nBase = sameCase(base);
-    const nBaseSep = sameCase(baseWithSep);
-    // 恰好等于 base 本身（极端的 rawPath='.' 情形）也视为合法，但 caller 一般
-    // 用的是具体文件；这里允许不报错。
-    if (nAbs !== nBase && !nAbs.startsWith(nBaseSep))
-        return null;
-    // 导出【相对 workingDir 的相对路径】（去掉 base 前缀）
-    const rel = abs.slice(base.length).replace(/^[/\\]/, '');
-    return rel.length === 0 ? '.' : rel;
-}
-/**
- * 表达式/任意场景的通用「绝对路径是否在 cwd 内」判定。
- *   - abs 必须是【已 resolve 后的绝对路径】
- *   - 越界/空 → false
- */
-export function isAbsWithinCwd(workingDir, abs) {
-    if (!abs)
-        return false;
-    const base = resolve(workingDir);
-    const baseWithSep = base.endsWith(sep) ? base : base + sep;
-    const sameCase = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
-    const nAbs = sameCase(abs);
-    return nAbs === sameCase(base) || nAbs.startsWith(sameCase(baseWithSep));
-}
-/**
- * 危险键黑名单：VarStack.set* / interpolateDeep 对象 key / 点路径访问统一过滤。
- * 防止原型污染 / 构造函数逃逸。与 expressions.ts parsePrimary S1 白名单保持一致。
- */
-export const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export {};