minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/src/runtime/context.js

@@ -0,0 +1,1304 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/runtime/context.ts —— WorkflowContext V2 组装
+ * ------------------------------------------------------------
+ *  对外形状由 workflowContextCapabilities.json 统一登记；本文件实现这些能力并
+ *  组装冻结的 wf 对象。工作流按受信任本地代码执行，不宣称安全沙箱。
+ *
+ *  **不在这里的东西，是因为 JS 原生就有**：if / for / while / break / continue /
+ *  try、JSON 与字符串处理。受控扇出统一使用 `wf.flow.pipeline()`，由运行时执行
+ *  有界调度和稳定恢复；业务分支本身仍是普通 JavaScript。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **哪些调用进账本**（journal），这条分界线是有原则的：
+ *
+ *    进账本：模型、工具、进程、询问和子工作流 —— 贵的、有副作用的、要问人的
+ *    不进账本：输出、进度、文件系统读写、确定性检查和状态读取
+ *
+ *  `exists()` / `readJson()` **绝不能重放** —— 重放会返回上次运行时的文件系统事实，
+ *  而 resume 的全部意义就在于「现在磁盘上到底有什么」。重跑既便宜又更正确。
+ *
+ *  ⚠️ **`llm_error` / `max_turns` 的 raw 事件不得原样漏给顶层**。真机事故：`-p` 模式
+ *  收到任意 `type:'error'` 就 `exitCode:1` 并 `process.exit()`，把整个进程杀死在
+ *  这里 —— 比脚本自己的 try/catch 还早，等于跳过了作者写的全部降级逻辑。
+ *  这两类信号在此转成抛出的 Error，交给脚本的 try/catch 处理。
+ * ============================================================
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { ALL_TOOLS, createAgentRuntimeContext, parseCheckString, recordRead, resolveProviderForModel, resolveProviderForWorkflowRole, runQuery, runVerification, executeTool as sdkExecuteTool, stripThinkBlocks, } from '../../../../src/plugin-sdk.js';
+import { withGoalAnchor } from '../goalAnchor.js';
+import { MAIN_LANE } from '../journal.js';
+import { extractJsonPayload } from '../jsonPayload.js';
+import { renderViolations, validateAgainstSchema, } from '../jsonSchema.js';
+import { buildWorkflowToolContext, effectiveWorkflowCwd, } from '../toolRuntime.js';
+import { truncate } from '../util.js';
+import { sharedWorkflowScheduler, } from './scheduler.js';
+import { executeWorkflowFile } from './exec.js';
+import { atomicWriteJson, atomicWriteText, ensureWorkflowDir, } from './fs.js';
+import { structuredWorkflowError } from './flow.js';
+import { assertWorkflowTimeout } from './model.js';
+import { workflowProgressEvent } from './output.js';
+import { workflowBudget } from './state.js';
+import { unknownToolNames } from './tools.js';
+import { assertWorkflowContextShape, } from '../workflowContext.js';
+/**
+ * 内核里**存在**的全部工具名 —— 用来区分「作者把名字拼错了」和
+ * 「名字对但宿主没授权」。这两种情况的处置完全不同，混在一起报会让
+ * 真正的拼写错误淹没在正常的宿主过滤里。
+ */
+const KNOWN_TOOL_NAMES = new Set(ALL_TOOLS.map((t) => t.name));
+/** One shared scope for the entire workflow tree. */
+export class ExecutionScope {
+    scheduler;
+    rootRunId;
+    calls = 0;
+    constructor(scheduler = sharedWorkflowScheduler(), rootRunId = randomUUID()) {
+        this.scheduler = scheduler;
+        this.rootRunId = rootRunId;
+    }
+}
+export function createWorkflowContext(deps) {
+    const { ctx, state, journal, emit, args, session, task, workflowDir } = deps;
+    const scope = deps.scope ?? new ExecutionScope();
+    const runId = deps.runId ?? task;
+    const parentRunId = deps.parentRunId;
+    const depth = deps.depth ?? 0;
+    const eventIdentity = {
+        workflow: deps.workflowName,
+        runId,
+        rootRunId: scope.rootRunId,
+        ...(parentRunId ? { parentRunId } : {}),
+        depth,
+    };
+    const emitProgressEvent = (update) => {
+        const event = workflowProgressEvent(eventIdentity, update);
+        emit(event);
+        void state.appendEvent(event).catch(() => undefined);
+    };
+    const modelScope = new AsyncLocalStorage();
+    const modelCall = async (opts, fn) => {
+        assertWorkflowTimeout(opts.timeoutMs);
+        const controller = new AbortController();
+        const timer = opts.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => controller.abort(new Error(`LLM 调用超过工作流步骤时限 ${opts.timeoutMs}ms（含排队和结构化修复）；保留断点，可重试。`)), opts.timeoutMs);
+        const signal = ctx.signal
+            ? AbortSignal.any([ctx.signal, controller.signal])
+            : controller.signal;
+        const start = Date.now();
+        const heartbeat = setInterval(() => {
+            const message = `${opts.label ?? '模型步骤'}：等待/执行中，已用 ${Math.round((Date.now() - start) / 1000)} 秒${opts.timeoutMs ? ` / 上限 ${Math.round(opts.timeoutMs / 1000)} 秒` : ''}`;
+            void state.appendProgress(`ℹ ${message}`).catch(() => { });
+            emitProgressEvent({
+                phase: 'model',
+                status: 'update',
+                message,
+                elapsedMs: Date.now() - start,
+            });
+        }, 30_000);
+        let failed = false;
+        try {
+            return await modelScope.run(signal, () => scope.scheduler.run('model', scope.rootRunId, async (queuedMs) => {
+                if (queuedMs > 0) {
+                    emitProgressEvent({
+                        phase: 'model',
+                        status: 'update',
+                        message: `${opts.label ?? '模型步骤'}：排队 ${queuedMs}ms 后开始`,
+                        queuedMs,
+                        elapsedMs: Date.now() - start,
+                    });
+                }
+                return fn();
+            }, signal));
+        }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            clearInterval(heartbeat);
+            emitProgressEvent({
+                phase: 'model',
+                status: failed ? 'warning' : 'complete',
+                message: `${opts.label ?? '模型步骤'}：${failed ? '失败' : '完成'}`,
+                elapsedMs: Date.now() - start,
+            });
+        }
+    };
+    const countCall = () => {
+        ctx.signal?.throwIfAborted();
+        scope.calls++;
+        if (scope.calls > scope.scheduler.config.maxCalls) {
+            throw new Error(`工作流调用次数超过上限 ${scope.scheduler.config.maxCalls} —— 请检查不收敛循环，或调整 MINIMAL_AGENT_WORKFLOW_MAX_CALLS。`);
+        }
+    };
+    /**
+     * 工作流启动时的 history 长度。`resetContext()` 截回这里 —— 那个位置上是刷新过的
+     * 稳定系统提示（含 Skills 目录），截到它意味着「回到干净的入口快照」而不是清空。
+     */
+    const historyBaseline = ctx.history.length;
+    // ---------------------------------------------------------------------
+    //  车道（lane）：并发下让账本定位保持确定
+    // ---------------------------------------------------------------------
+    //
+    // 账本按「车道内序号」定位，而车道内是严格串行的，所以序号与调度无关。
+    // 当前车道靠 AsyncLocalStorage 随 await 链传播 —— 模块级变量在并发交错下必错。
+    const laneStore = new AsyncLocalStorage();
+    const currentLane = () => laneStore.getStore() ?? MAIN_LANE;
+    /** 每条车道内的 pipeline 计数器：嵌套扇出的车道名也要确定。 */
+    const pipelineCounters = new Map();
+    const childCounters = new Map();
+    const nextPipelineId = (lane) => {
+        const n = (pipelineCounters.get(lane) ?? 0) + 1;
+        pipelineCounters.set(lane, n);
+        return n;
+    };
+    /** 展示用序号（▶/✓ 配对），与账本定位无关。 */
+    let displaySeq = 0;
+    // 同一车道上并发发起记账调用 = 该车道序号取决于调度 = resume 会失效。
+    // 这是**作者用错了 API** 的信号（裸 `Promise.all` 套 agent），报一次就够。
+    const laneActive = new Map();
+    let warnedConcurrentLane = false;
+    const noteLaneEntry = (lane) => {
+        const n = (laneActive.get(lane) ?? 0) + 1;
+        laneActive.set(lane, n);
+        if (n > 1 && !warnedConcurrentLane) {
+            warnedConcurrentLane = true;
+            emit({
+                type: 'warning',
+                message: '⚠ 同一条执行链上有并发的记账调用（多半是裸 `Promise.all([agent(...), agent(...)])`）。' +
+                    '这会让账本序号取决于谁先返回，**断点续跑随之失效**。改用 `pipeline(items, 阶段…)` —— ' +
+                    '它给每一项一条确定的车道，扇出与 resume 可以兼得。',
+            });
+        }
+    };
+    const noteLaneExit = (lane) => {
+        const n = (laneActive.get(lane) ?? 1) - 1;
+        if (n <= 0)
+            laneActive.delete(lane);
+        else
+            laneActive.set(lane, n);
+    };
+    // ---------------------------------------------------------------------
+    //  model 选项：按 id 解析 provider，解析不到就回落基座并告警
+    // ---------------------------------------------------------------------
+    const providerCache = new Map();
+    const warnedModels = new Set();
+    const resolveModel = async (modelId) => {
+        if (!modelId)
+            return undefined;
+        if (!providerCache.has(modelId)) {
+            let resolved = null;
+            try {
+                // A portable workflow role wins when mapped on this machine. Otherwise
+                // retain backwards compatibility with explicit local model ids.
+                resolved =
+                    (await resolveProviderForWorkflowRole(modelId)) ??
+                        (await resolveProviderForModel(modelId));
+            }
+            catch {
+                resolved = null; // 配置读不动 → 当解析不到处理，绝不让它拖垮工作流
+            }
+            providerCache.set(modelId, resolved);
+        }
+        const provider = providerCache.get(modelId) ?? null;
+        if (!provider) {
+            if (!warnedModels.has(modelId)) {
+                warnedModels.add(modelId);
+                emit({
+                    type: 'warning',
+                    message: `⚠ 找不到模型「${modelId}」（工作流角色未映射、模型不存在或没填 API Key），本步回落到基座模型。随包工作流应声明 capability role，不应写死机器本地模型 id。`,
+                });
+            }
+            return undefined;
+        }
+        return provider;
+    };
+    /** Fail before expensive work when a workflow's declared model capability is absent. */
+    const requireModel = async (role, needs = {}) => {
+        // Role mappings are optional overrides. This keeps packaged workflows
+        // usable in CLI/Desktop before either surface grows a role-mapping UI.
+        // resolveModel already emits one visible fallback warning when unmapped.
+        const provider = (await resolveModel(role)) ?? ctx.provider;
+        if (needs.vision && provider.supportsVision !== true) {
+            throw new Error(`工作流角色「${role}」未映射到可用的视觉模型，且当前基座模型也不支持视觉输入。`);
+        }
+        if (needs.jsonSchema && provider.supportsJsonSchema !== true) {
+            throw new Error(`工作流角色「${role}」的映射模型/基座模型未声明可靠 JSON Schema 支持。`);
+        }
+        return {
+            role,
+            model: provider.model,
+            supportsVision: provider.supportsVision === true,
+            supportsJsonSchema: provider.supportsJsonSchema === true,
+        };
+    };
+    // ---------------------------------------------------------------------
+    //  schema：校验 + 有界修复
+    // ---------------------------------------------------------------------
+    /** 修复轮数上限。够纠正格式问题，又不至于在一个搞不定的 schema 上烧钱。 */
+    const SCHEMA_REPAIR_ROUNDS = 2;
+    /**
+     * provider 原生结构化输出的参数片段 —— **只对 OpenAI 格式给**。
+     *
+     * Anthropic 格式的 provider 上 `chat()` 会在发请求前直接抛错，那会把一次本可以
+     * 靠「校验 + 修复」完成的调用变成硬失败。所以原生约束是加成，可移植的地板是
+     * 引擎侧的校验与修复循环。`test/api.schema.test.ts` 锁住「Anthropic 不得抛」。
+     */
+    const nativeSchema = (provider, schema, enabled = true) => !enabled ||
+        provider.apiFormat === 'anthropic' ||
+        provider.supportsJsonSchema === false
+        ? {}
+        : { responseFormat: toResponseFormat(schema) };
+    const toResponseFormat = (schema) => ({
+        type: 'json_schema',
+        json_schema: {
+            name: 'workflow_output',
+            schema: schema,
+            strict: false,
+        },
+    });
+    /**
+     * `isolated: true` 时给出一份全新 history：只带稳定系统提示。
+     *
+     * ⚠️ **不得触碰 `historyBaseline`** —— 那是 `resetContext()` 截回的锚点，
+     * 指向主线 history 里刷新过的系统提示。隔离调用完全不碰主线，锚自然不动。
+     */
+    const isolatedHistory = (isolated) => {
+        if (!isolated)
+            return undefined;
+        const system = ctx.history[0];
+        return system && system.role === 'system' ? [{ ...system }] : [];
+    };
+    /** 从模型文本里抽出 JSON 并校验；返回对象或 null（附违规清单）。 */
+    const parseAndValidate = (text, schema) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(extractJsonPayload(stripThinkBlocks(String(text ?? ''))));
+        }
+        catch (e) {
+            return {
+                value: null,
+                violations: `  · (根)：不是合法 JSON —— ${e instanceof Error ? e.message : e}`,
+            };
+        }
+        const violations = validateAgainstSchema(parsed, schema);
+        if (violations.length === 0)
+            return { value: parsed, violations: [] };
+        return { value: null, violations: renderViolations(violations) };
+    };
+    /**
+     * 把一次「产文本」的调用变成「产校验过的对象」。
+     *
+     * ⚠️ **整个修复循环必须在 journaled 的 `run()` 内部**：一次逻辑调用只该记一条账，
+     * 记录的是**校验后的对象**（重放时直接拿到对象，不必再解析一遍，也就不会
+     * 在重放路径上重演解析失败）。把修复摊成多条账会让车道序号随修复次数漂移。
+     */
+    const withSchema = async (schema, first, repair) => {
+        let text = await first();
+        let attempt = 0;
+        for (;;) {
+            const r = parseAndValidate(text, schema);
+            if (r.value !== null)
+                return r.value;
+            if (attempt >= SCHEMA_REPAIR_ROUNDS) {
+                throw new Error(`结构化输出在 ${SCHEMA_REPAIR_ROUNDS} 次修复后仍不符合 schema：\n${r.violations}\n` +
+                    `最后一次原始输出（截断）：${truncate(String(text ?? '').replace(/\s+/g, ' '), 300)}`);
+            }
+            attempt++;
+            emit({
+                type: 'warning',
+                message: `↻ 结构化输出不合 schema，第 ${attempt}/${SCHEMA_REPAIR_ROUNDS} 次修复：\n${r.violations}`,
+            });
+            text = await repair(`你上一次的输出不符合要求的 JSON Schema。逐条问题如下：\n${r.violations}\n\n请**只输出修正后的 JSON**，不要任何解释、不要 markdown 代码围栏。\n需要满足的 Schema：\n${JSON.stringify(schema)}\n\n你上一次的输出：\n${truncate(String(text ?? ''), 4000)}`);
+        }
+    };
+    /** 把 contextFiles 渲染成一段「有这些文件可读」的提示，不 inline 内容。 */
+    const renderContextFiles = (files) => {
+        if (!files?.length)
+            return '';
+        const lines = files.map((f) => f.hint ? `  · ${f.path} —— ${f.hint}` : `  · ${f.path}`);
+        return `\n\n可供参考的文件（**按需用 Read 打开**，不要假设内容）：\n${lines.join('\n')}`;
+    };
+    /** 跑一轮 runQuery 并归纳结果。llm_error / max_turns 转成抛出的 Error。 */
+    const query = async (prompt, opts) => {
+        const history = opts.history ?? ctx.history;
+        const hostTools = new Set((ctx.tools ?? []).map((t) => t.name));
+        const allowed = opts.allowedTools === undefined
+            ? [...hostTools]
+            : opts.allowedTools.filter((n) => hostTools.has(n));
+        // ⚠️ 过滤掉的名字必须报出来，而且要**区分两种原因** ——
+        //   · 名字压根不存在（拼错了：'WriteFile' 而不是 'Write'）→ 作者的 bug，响亮警告
+        //   · 名字存在但宿主没授权 → 宿主策略，说明一下即可
+        // 早先这里只 filter 不吭声：作者拼错一个工具名，agent 就少了那个能力，
+        // 然后它要么绕路、要么烂尾，而 progress.md 里**什么都看不出来**。
+        if (opts.allowedTools?.length) {
+            const missing = opts.allowedTools.filter((n) => !hostTools.has(n));
+            if (missing.length > 0) {
+                const unknown = unknownToolNames(missing, KNOWN_TOOL_NAMES);
+                const filtered = missing.filter((n) => KNOWN_TOOL_NAMES.has(n));
+                if (unknown.length > 0) {
+                    emit({
+                        type: 'warning',
+                        message: `⚠ allowedTools 里有 ${unknown.length} 个**不存在**的工具名：${unknown.join('、')}。拼错的名字会被静默丢掉，agent 因此少了这些能力。跑 \`node skills/workflow-creator/scripts/list-resources.mjs --tools\` 看全部可用工具名。`,
+                    });
+                }
+                if (filtered.length > 0) {
+                    emit({
+                        type: 'warning',
+                        message: `ℹ allowedTools 里的 ${filtered.join('、')} 存在但本次运行的宿主没授权，已跳过。`,
+                    });
+                }
+            }
+        }
+        const historyLenBefore = history.length;
+        const runtimeContext = createAgentRuntimeContext({
+            ...(ctx.runtimeContext ?? {
+                surface: 'workflow',
+                profile: 'main',
+                interactiveAsk: false,
+            }),
+            cwd: effectiveWorkflowCwd(ctx),
+            owner: ctx.runtimeContext?.owner ?? 'untrusted',
+            memoryAccess: ctx.runtimeContext?.memoryAccess ?? 'denied',
+        });
+        const requestSignal = modelScope.getStore() ?? ctx.signal;
+        requestSignal?.throwIfAborted();
+        const capabilityContext = buildWorkflowToolContext(ctx, `wf-model-${task}-${randomUUID()}`, () => undefined, opts.uses);
+        if ('error' in capabilityContext)
+            throw new Error(capabilityContext.error);
+        let llmError = '';
+        let maxTurnsHit = false;
+        let sawToolCall = false;
+        let usage;
+        const toolNames = [];
+        const selectedProvider = opts.provider ?? ctx.provider;
+        const boundedProvider = opts.maxTokens && opts.maxTokens > 0
+            ? {
+                ...selectedProvider,
+                maxTokens: typeof selectedProvider.maxTokens === 'number'
+                    ? Math.min(selectedProvider.maxTokens, opts.maxTokens)
+                    : opts.maxTokens,
+            }
+            : selectedProvider;
+        for await (const ev of runQuery(prompt, {
+            provider: boundedProvider,
+            runtimeContext,
+            history,
+            signal: requestSignal,
+            maxTurns: opts.maxTurns,
+            allowedTools: allowed,
+            ...(opts.allowedTools === undefined ? {} : { requiredTools: allowed }),
+            chat: ctx.chat,
+            executeTool: ctx.executeTool,
+            sessionState: ctx.sessionState,
+            ...(opts.responseFormat ? { responseFormat: opts.responseFormat } : {}),
+            ...(opts.images?.length
+                ? {
+                    imageInputs: opts.images.map((i) => typeof i === 'string' ? { source: i } : i),
+                }
+                : {}),
+            transientContext: ctx.transientContext,
+            inputResources: ctx.inputResources,
+            transientBundle: ctx.transientBundle,
+            promptCache: ctx.promptCache,
+            ...(capabilityContext.computerRun
+                ? { computerRun: capabilityContext.computerRun }
+                : {}),
+            ...(capabilityContext.computerIntervention
+                ? { computerIntervention: capabilityContext.computerIntervention }
+                : {}),
+            ...(capabilityContext.browserRun
+                ? { browserRun: capabilityContext.browserRun }
+                : {}),
+            ...(capabilityContext.toolGate
+                ? { toolGate: capabilityContext.toolGate }
+                : {}),
+        })) {
+            if (ev.type === 'error') {
+                if (ev.code === 'llm_error') {
+                    llmError = ev.error;
+                    continue; // ⚠️ 见文件头注：不得漏给顶层，否则 -p 直接杀进程
+                }
+                if (ev.code === 'max_turns') {
+                    maxTurnsHit = true;
+                    continue; // 同上
+                }
+            }
+            else if (ev.type === 'tool_start' || ev.type === 'tool_end') {
+                sawToolCall = true;
+                if (!toolNames.includes(ev.toolName))
+                    toolNames.push(ev.toolName);
+            }
+            // turn_done 是本次 runQuery 的收尾，不是整条工作流的收尾 —— 吞掉，
+            // 否则宿主会以为工作流已经结束。⚠️ 但吞掉之前要把它带的资源账本取走：
+            // 这是本次调用花了多少 token 的唯一来源，丢了预算闸就没有刻度。
+            if (ev.type === 'turn_done') {
+                usage = ev.usage;
+                continue;
+            }
+            // Isolated calls are internal workers. Their committed messages may contain base64
+            // images and reasoning; forwarding them makes Desktop look as if a completed
+            // workflow is still chatting. Keep only explicit workflow progress/warnings/errors.
+            if (opts.isolated && ev.type !== 'warning' && ev.type !== 'error')
+                continue;
+            // ⚠️ **模型的原始文本不外泄**：`llm()`/`agent()` 在工作流里是**产值调用**，
+            // 产出交给脚本，由脚本用 `echo()` 决定给用户看什么。全放出去有两个实际
+            // 后果：① 二十步的工作流糊出一堵墙；② `-p --output-format json` 的
+            // `result` 字段（累积的 assistant 文本）被中间产物污染，宿主拿不到干净结论。
+            // 工具活动与进度照常发 —— 用户仍然看得见「在干什么」。
+            // ⚠️ 只吞 `text`，**不吞 `assistant_message`**：后者在 print.ts 里只给
+            // `num_turns` 计数、不进 result buffer，吞掉它只会让宿主看到「0 轮」
+            // 却做了真活；而 TUI 侧它也不负责渲染内容（MessageList 从 history 渲染，
+            // runQuery 已直接 push），吞了照样挡不住显示。纯亏。
+            if (ev.type === 'text')
+                continue;
+            emit(ev);
+        }
+        requestSignal?.throwIfAborted();
+        // 从 history 反查本次产出的最后一条非空 assistant 文本。
+        // 经 stripThinkBlocks 净化：末条若是纯 <think>（模型收尾只剩思考）继续往前找 ——
+        // 拿到手的必须是交付文本，不是思考过程。
+        let text = '';
+        for (let i = history.length - 1; i >= historyLenBefore; i--) {
+            const msg = history[i];
+            if (msg.role === 'assistant' && typeof msg.content === 'string') {
+                const cleaned = stripThinkBlocks(msg.content).trim();
+                if (cleaned) {
+                    text = cleaned;
+                    break;
+                }
+            }
+        }
+        if (llmError && !text) {
+            throw new Error(`LLM 调用失败：${llmError}`);
+        }
+        if (maxTurnsHit) {
+            throw new Error(`撞到轮数上限 ${opts.maxTurns} 被截断 —— 此刻的产出是半截工作叙述而不是可信交付。请提高 maxTurns，或把任务拆小。`);
+        }
+        return { text, sawToolCall, toolNames, usage };
+    };
+    /**
+     * 把一次调用的用量记进账本。
+     *
+     * ⚠️ **必须在 journaled 回调内部调用**：账本重放命中时那个回调根本不执行，
+     * 于是重放天然不重复记账。挪到外面就会每次 resume 都把历史用量再加一遍。
+     *
+     * ⚠️ provider 没报 usage 时（`usage.trustworthy === false`）照样把已知部分记进去，
+     * 但把 ledger 的 trustworthy 拉黑 —— 让 `budget()` 的消费方知道这份账偏低。
+     * 直接跳过不记会更糟：那等于默认「没报 = 没花」。
+     */
+    const recordCallUsage = async (usage) => {
+        if (!usage)
+            return;
+        ctx.resourceLedger ??= {
+            inputTokens: 0,
+            outputTokens: 0,
+            limit: null,
+            trustworthy: true,
+        };
+        const ledger = ctx.resourceLedger;
+        if (!usage.trustworthy)
+            ledger.trustworthy = false;
+        const recordUsage = ctx.usageRecorder ??
+            ctx.managedBridge?.recordUsage?.bind(ctx.managedBridge);
+        if (recordUsage) {
+            // 有外层控制器 → 以它持久化的累计快照为准（跨进程 resume 不丢账）。
+            try {
+                const snap = await recordUsage({
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                });
+                ledger.inputTokens = snap.inputTokens;
+                ledger.outputTokens = snap.outputTokens;
+                ledger.limit = snap.limit;
+                return;
+            }
+            catch {
+                // 记账失败不能让工作流挂掉 —— 退回进程内累计并拉黑可信度。
+                ledger.trustworthy = false;
+            }
+        }
+        ledger.inputTokens += usage.inputTokens;
+        ledger.outputTokens += usage.outputTokens;
+    };
+    /** 上一条 text 输出是否以换行收尾 —— echo() 据此决定要不要补一个前置换行。 */
+    let lastEmittedEndedWithNewline = true;
+    /**
+     * 给**脚本自己**读文件用的确定性读取（`readText` / `readJson` 的共同实现）。
+     *
+     * ⚠️ **刻意不走 `Read` 工具**。那个工具的输出是**给模型看**的，带两样对程序化
+     * 调用有害的东西：
+     *   ① 每行的 `<行号><TAB>` 前缀；
+     *   ② 重复读同一文件时开头插一句「⚠️ 重复读取空转：该区间未变化…」。
+     * 第 ② 条尤其阴险 —— 它只在**第二次**读时出现，于是同一段代码时对时错。
+     * 真实事故：research 阶段2 的 agent 写完 branches.json 后自己 Read 校验了一遍，
+     * 脚本随后 `readJson()` 就命中这条提示、`JSON.parse` 失败、静默返回 null，
+     * 最后报出来的是「JSON 格式错误或数组为空」——而那个文件完全合法。
+     *
+     * 相对路径基于 `effectiveWorkflowCwd` 解析（进了 worktree 就跟着走）。
+     */
+    const readFileForScript = async (path) => {
+        try {
+            const base = effectiveWorkflowCwd(ctx);
+            if (isAbsolute(path))
+                return await readFile(path, 'utf8');
+            // User data remains rooted at the effective workspace cwd. If that path
+            // does not exist, also resolve the documented package-resource form
+            // (`workflows/<name>/...`) against the discovered workflow root. Desktop
+            // runs commonly use a workspace outside the installed package, so without
+            // this fallback bundled prompts fail with a misleading "missing prompt".
+            const candidates = [resolve(base, path)];
+            if (workflowDir) {
+                candidates.push(resolve(workflowDir, path));
+                candidates.push(resolve(dirname(dirname(workflowDir)), path));
+            }
+            for (const candidate of [...new Set(candidates)]) {
+                try {
+                    return await readFile(candidate, 'utf8');
+                }
+                catch {
+                    // Try the next resource root; a missing workspace file is normal.
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const progress = (message) => {
+        emitProgressEvent({ phase: 'step', status: 'update', message });
+    };
+    const runScheduled = async (resource, label, run) => {
+        const queuedAt = Date.now();
+        return scope.scheduler.run(resource, scope.rootRunId, async (queuedMs) => {
+            const startedAt = Date.now();
+            emitProgressEvent({
+                phase: resource,
+                status: 'start',
+                message: label,
+                queuedMs,
+                elapsedMs: startedAt - queuedAt,
+            });
+            try {
+                return await run();
+            }
+            finally {
+                emitProgressEvent({
+                    phase: resource,
+                    status: 'complete',
+                    message: label,
+                    queuedMs,
+                    elapsedMs: Date.now() - startedAt,
+                });
+            }
+        }, ctx.signal);
+    };
+    /** `tool()` 与 `toolResult()` 的共同实现 —— 走同一条账本与授权路径。 */
+    const callTool = async (name, input, opts) => journaled('tool', `🔧 ${name}`, { name, input, uses: opts.uses ?? null }, async () => {
+        const toolCallId = `wf-${task}-${randomUUID()}`;
+        const built = buildWorkflowToolContext(ctx, toolCallId, () => undefined, opts.uses);
+        if ('error' in built)
+            throw new Error(built.error);
+        // Write 工具有「覆盖已存在文件前必须先 Read 过」的防手滑闸门——那是为
+        // agent 在长对话里可能凭过时印象盲写设计的。工作流脚本的 tool('Write', …)
+        // 不是这种情况：它是作者写死的、无条件覆盖自己声明的产物路径（CONTRACT.md/
+        // STATUS.json/manifest.json 这类），语义上就是"这次跑完的最新状态"，
+        // 从不依赖"没人动过"这个假设。断点续跑（尤其 goal/ralph-loop 这类跨进程
+        // 恢复的 managedRuntime 工作流）天然会在一个**全新进程**里对着上一次尝试
+        // 已经写过的路径再写一遍——新进程的 sessionState 从空白起步，闸门会把
+        // "从没人读过"误判成"可能盲写覆盖外部改动"，实际内容完全正确也照样拒绝。
+        // 用 recordRead 在动手之前把当前磁盘内容"报到"给同一份 freshness 状态，
+        // 等价于工作流自己先 Read 了一遍——不改闸门本身（agent 走普通 Write 时这
+        // 层保护原样保留），只解除它对确定性脚本重复覆盖自身产物的误伤。
+        if (name === 'Write') {
+            const target = String(input.file_path ?? '');
+            if (target) {
+                // resolve() 而不是 isAbsolute() 分支：即便 target 已是绝对路径，
+                // 也要走同一次 resolve 规范化（盘符大小写、正斜杠/反斜杠混用），
+                // 否则这里算出的 key 和 write.ts::validateAndResolvePath 算出的
+                // 不是同一个字符串，Map 查找对不上，等于没修——曾经这样漏过一次。
+                const abs = resolve(effectiveWorkflowCwd(ctx), target);
+                if (existsSync(abs))
+                    recordRead(abs, {}, built.sessionState?.fileReads);
+            }
+        }
+        const exec = ctx.executeTool ?? sdkExecuteTool;
+        const r = await runScheduled('tool', name, () => exec(name, JSON.stringify(input), ctx.signal, built));
+        if (!r.ok)
+            throw new Error(`工具 ${name} 失败：${r.error}`);
+        return {
+            content: r.content,
+            images: (r.visionImages ?? [])
+                .map((img) => (typeof img.source === 'string' ? img.source : ''))
+                .filter((p) => p.length > 0),
+            metadata: r.metadata,
+        };
+    });
+    /**
+     * 记一次引擎中介调用：状态行显示 + **落盘 progress.md**。
+     *
+     * ⚠️ 落盘那半不是锦上添花。TUI 的 scrollback 会被刷掉，而排障几乎总是发生在
+     * 「跑完之后」—— 一条跑了五分钟、九次调用的工作流出了问题，唯一还能回看的现场
+     * 就是这个文件。legacy 的 progress.md 逐步记录，新引擎一开始只写了最后一行
+     * 「✓ 完成」，等于把这个能力丢了（真实 plan 端到端跑完才发现）。
+     *
+     * 失败也要记 —— 只记成功等于把最需要看的那条抹掉。
+     */
+    const journaled = async (kind, label, args_, run, alreadyCounted = false) => {
+        if (!alreadyCounted)
+            countCall();
+        progress(label);
+        const lane = currentLane();
+        // 展示序号用引擎自己的计数器：账本的写入序号在并发下是「谁先返回谁先写」，
+        // 拿它当 ▶/✓ 的配对号会串行。这个只用于人眼配对，不参与任何定位。
+        const seq = ++displaySeq;
+        noteLaneEntry(lane);
+        // fire-and-forget（同 258/1650/1660 行的心跳/structuredProgress/log()）：
+        // WorkflowState.appendProgress 内部的 progressWrites 链在第一个 await 之前就把
+        // 写入按调用顺序排进队，调用方等不等待不影响落盘顺序。journaled() 是
+        // agent/llm/skill/tool/sh/execFile 的唯一必经关卡，同步等待这三次磁盘往返会把
+        // 调度器本该提供的并发压成串行（实测：16 路并发 generate() 因此只叠出 2-3 路
+        // 峰值）。落盘保证由 runner.ts 每条终止路径（中断/失败/成功）对同一条
+        // progressWrites 链的 await 兜底——那次等待会等到它之前排队的全部写入都完成，
+        // 不需要在这里额外补 flush。
+        void state.appendProgress(`▶ #${seq} ${kind}: ${label}`).catch(() => { });
+        try {
+            const r = await journal.step(kind, args_, run, lane);
+            const preview = truncate(String(typeof r === 'object' && r !== null ? JSON.stringify(r) : (r ?? ''))
+                .replace(/\s+/g, ' ')
+                .trim(), 120);
+            void state.appendProgress(`✓ #${seq} ${kind}: ${preview}`).catch(() => { });
+            return r;
+        }
+        catch (e) {
+            void state
+                .appendProgress(`✗ #${seq} ${kind}: ${e instanceof Error ? e.message : String(e)}`)
+                .catch(() => { });
+            throw e;
+        }
+        finally {
+            noteLaneExit(lane);
+        }
+    };
+    const capabilities = {
+        args,
+        session,
+        task,
+        goal: ctx.goalAnchor ?? '',
+        // Absolute directory of the discovered workflow. This is for immutable
+        // bundled resources (prompts/scripts), not user output; output paths remain
+        // relative to the effective workspace cwd.
+        workflowDir: workflowDir ?? '',
+        // Bound input resources are runtime-only host paths. Do not persist or publish them.
+        resources: deps.inputResourceMap ?? {},
+        /** Validate a portable model role before the workflow starts costly image work. */
+        requireModel,
+        /** 有界 TAOR 子任务：模型自主选工具干活。 */
+        agent: async (prompt, opts = {}) => {
+            // 默认 true：账本重放命中时 run 回调根本不执行，此值保持不变 —— 不该为
+            // 一次「上次已经报过」的调用重复报警。只有真跑过才可能被置成 false。
+            let sawTools = true;
+            const seq = ++displaySeq;
+            const provider = await resolveModel(opts.model);
+            const history = isolatedHistory(opts.isolated);
+            const text = await modelCall(opts, () => journaled('agent', `🤖 ${opts.label ?? truncate(prompt, 40)}`, 
+            // ⚠️ provider 的**真实 model 串**必须进指纹：同一份脚本换台机器解析到
+            // 另一个模型时，指纹若不变就会拿 A 模型的结果冒充 B 模型的 —— 与账本
+            // 要挡的那类静默错误同源。schema 同理（换 schema = 换契约）。
+            {
+                prompt,
+                allowedTools: opts.allowedTools ?? null,
+                uses: opts.uses ?? null,
+                images: opts.images ?? null,
+                contextFiles: opts.contextFiles ?? null,
+                maxTurns: opts.maxTurns ?? 60,
+                model: provider?.model ?? null,
+                schema: opts.schema ?? null,
+                nativeSchema: opts.nativeSchema ?? true,
+                isolated: opts.isolated ?? false,
+                timeoutMs: opts.timeoutMs ?? null,
+                maxTokens: opts.maxTokens ?? null,
+            }, async () => {
+                const run = async (p) => {
+                    const r = await query(p, {
+                        maxTurns: opts.maxTurns ?? 60,
+                        allowedTools: opts.allowedTools,
+                        uses: opts.uses,
+                        images: opts.images,
+                        maxTokens: opts.maxTokens,
+                        ...(provider ? { provider } : {}),
+                        ...(history ? { history } : {}),
+                        isolated: opts.isolated,
+                    });
+                    sawTools = r.sawToolCall;
+                    // 记账在 journaled 回调内 → 重放不重复计（见 recordCallUsage 头注）。
+                    // schema 的修复轮也走这里，每一轮都真花了钱，都要记。
+                    await recordCallUsage(r.usage);
+                    return r.text;
+                };
+                const anchored = withGoalAnchor(ctx, prompt + renderContextFiles(opts.contextFiles));
+                if (!opts.schema)
+                    return run(anchored);
+                // ⚠️ 带工具的循环**不能**开 provider 原生 response_format：那会强制每条
+                // assistant 消息都是 JSON，而工具调用轮带的是 tool_calls，两者互斥。
+                // 所以 agent 走「先带工具把活干完，再零工具把结论整形」——修复轮才开原生约束。
+                return withSchema(opts.schema, () => run(anchored), (instruction) => query(instruction, {
+                    maxTurns: 1,
+                    allowedTools: [],
+                    uses: opts.uses,
+                    ...(provider ? { provider } : {}),
+                    ...(history ? { history } : {}),
+                    isolated: opts.isolated,
+                    maxTokens: opts.maxTokens,
+                    ...nativeSchema(provider ?? ctx.provider, opts.schema, opts.nativeSchema !== false),
+                }).then(async (r) => {
+                    await recordCallUsage(r.usage);
+                    return r.text;
+                }));
+            }));
+            // ⚠️ **announce-not-do 的廉价通用信号**：agent 产出了文本却一次工具都没调，
+            // 几乎总是「宣告我将要做…」然后停下 —— 弱模型的典型烂尾。legacy 靠 `done_when`
+            // 声明来兜，代码形态里守卫是作者写的，作者忘了写时这条就是唯一的线索。
+            //
+            // 只记录不抛：有些 agent 调用本就该纯思考（分类、判断、总结），报错会误伤。
+            // 落进 progress.md 是关键 —— TUI 会刷掉，而排障总发生在跑完之后。
+            if (!sawTools && String(text ?? '').trim()) {
+                const hint = `⚠ #${seq} agent 零工具调用：「${truncate(opts.label ?? prompt, 40)}」产出了文本但一次工具都没调`;
+                await state.appendProgress(hint);
+                emit({
+                    type: 'warning',
+                    message: `${hint} —— 若这一步本该产出东西，多半是 announce-not-do 烂尾，请在其后加 exists()/verify() 核实。`,
+                });
+            }
+            return text;
+        },
+        /** 纯文本生成，不给任何工具（弱模型也跑得动）。 */
+        llm: async (prompt, opts = {}) => {
+            const provider = await resolveModel(opts.model);
+            const history = isolatedHistory(opts.isolated);
+            return modelCall(opts, () => journaled('llm', `✍ ${opts.label ?? truncate(prompt, 40)}`, {
+                prompt,
+                allowedTools: opts.allowedTools ?? null,
+                uses: opts.uses ?? null,
+                images: opts.images ?? null,
+                contextFiles: opts.contextFiles ?? null,
+                maxTurns: opts.maxTurns ?? 1,
+                model: provider?.model ?? null,
+                schema: opts.schema ?? null,
+                nativeSchema: opts.nativeSchema ?? true,
+                isolated: opts.isolated ?? false,
+                timeoutMs: opts.timeoutMs ?? null,
+                maxTokens: opts.maxTokens ?? null,
+            }, async () => {
+                // ⚠️ 带图时**不能**锁死无工具：识图要模型看得见图，而 contextFiles
+                //   往往还要它 Read。纯文本场景才是零工具。
+                const allowedTools = opts.allowedTools ?? (opts.contextFiles ? ['Read'] : []);
+                const run = async (p, tools = allowedTools) => {
+                    const r = await query(p, {
+                        maxTurns: opts.maxTurns ?? 1,
+                        allowedTools: tools,
+                        uses: opts.uses,
+                        images: opts.images,
+                        maxTokens: opts.maxTokens,
+                        ...(provider ? { provider } : {}),
+                        ...(history ? { history } : {}),
+                        isolated: opts.isolated,
+                        // 零工具时才开原生约束（有工具会与 tool_calls 互斥）。
+                        ...(opts.schema && tools.length === 0
+                            ? nativeSchema(provider ?? ctx.provider, opts.schema, opts.nativeSchema !== false)
+                            : {}),
+                    });
+                    // 同 agent()：记账在 journaled 回调内，重放不重复计。
+                    await recordCallUsage(r.usage);
+                    return r.text;
+                };
+                const anchored = withGoalAnchor(ctx, prompt + renderContextFiles(opts.contextFiles));
+                if (!opts.schema)
+                    return run(anchored);
+                return withSchema(opts.schema, () => run(anchored), 
+                // 修复轮一律零工具：此刻要的是整形，不是再干一遍活。
+                (instruction) => run(instruction, []));
+            }));
+        },
+        /**
+         * 把对话历史截回工作流入口的干净快照（对应 yaml 的 `fresh_context: true`）。
+         *
+         * 长循环里每轮都带着前几十轮的对话跑，模型会被旧上下文带偏，token 也线性膨胀。
+         * 截回的位置是**刷新过的稳定系统提示**（含 Skills 目录），不是清空 —— 清空会
+         * 让后续调用失去地基信息。
+         *
+         * ⚠️ 不影响账本：journal 记的是调用序号与内容指纹，与 history 无关。
+         */
+        resetContext: () => {
+            if (ctx.history.length > historyBaseline) {
+                ctx.history.length = historyBaseline;
+            }
+        },
+        /** 跑一个 SKILL.md 定义的完整 agent。 */
+        skill: async (name, input, opts = {}) => {
+            const provider = await resolveModel(opts.model);
+            const history = isolatedHistory(opts.isolated);
+            return modelCall(opts, () => journaled('skill', `🧩 skill ${name}`, {
+                name,
+                input,
+                allowedTools: opts.allowedTools ?? null,
+                uses: opts.uses ?? null,
+                images: opts.images ?? null,
+                contextFiles: opts.contextFiles ?? null,
+                maxTurns: opts.maxTurns ?? 60,
+                model: provider?.model ?? null,
+                schema: opts.schema ?? null,
+                nativeSchema: opts.nativeSchema ?? true,
+                isolated: opts.isolated ?? false,
+                timeoutMs: opts.timeoutMs ?? null,
+                maxTokens: opts.maxTokens ?? null,
+            }, async () => {
+                const prompt = withGoalAnchor(ctx, `请使用 skill「${name}」完成以下任务：\n\n${input}${renderContextFiles(opts.contextFiles)}`);
+                const run = async (value, allowedTools = opts.allowedTools, responseFormat) => {
+                    const result = await query(value, {
+                        maxTurns: opts.maxTurns ?? 60,
+                        allowedTools,
+                        uses: opts.uses,
+                        images: opts.images,
+                        maxTokens: opts.maxTokens,
+                        ...(provider ? { provider } : {}),
+                        ...(history ? { history } : {}),
+                        isolated: opts.isolated,
+                        ...(responseFormat ? { responseFormat } : {}),
+                    });
+                    await recordCallUsage(result.usage);
+                    return result.text;
+                };
+                if (!opts.schema)
+                    return run(prompt);
+                return withSchema(opts.schema, () => run(prompt), (instruction) => run(instruction, [], nativeSchema(provider ?? ctx.provider, opts.schema, opts.nativeSchema !== false).responseFormat));
+            }));
+        },
+        /** 确定性地调一个原子工具，返回它的文本结果。 */
+        tool: async (name, input = {}, opts = {}) => {
+            const r = await callTool(name, input, opts);
+            return r.content;
+        },
+        /**
+         * 调工具并拿到**完整结果**：`{ content, images, metadata }`。
+         *
+         * `tool()` 只给 content 字符串 —— 绝大多数场景要的就是它。但有些工具的产出
+         * **根本不在文本里**：ComputerUse 的 `observe` 返回截图，任何看图类工具都一样。
+         * 只取 content 的话那些图**被静默丢弃**，后续要看图的步骤没图可用，还不报错。
+         *
+         * ⚠️ legacy 引擎为这件事专门修过一次（`stepExecutors/tool.ts` 里那段
+         * 「工具返回的图片不能丢」的注释），新引擎一开始又漏了同一处 ——
+         * 迁移 wechat-reading-shots 时才发现。
+         *
+         * `images` 取的是**路径字符串数组**而不是整个 `ImageInputSpec`：消费方要的是
+         * 能直接喂给 `llm(prompt, { images: [...] })` 的东西，结构体传下去反而要每个
+         * 消费方各自解包。这条判断也是照搬 legacy 的。
+         */
+        toolResult: async (name, input = {}, opts = {}) => callTool(name, input, opts),
+        /**
+         * 跑一条 shell 命令，返回**结构化**结果 `{ stdout, stderr, exitCode }`。
+         *
+         * 为什么值得单开一个名字（而不是让作者自己调 `tool('Bash', …)`）：
+         * Bash 工具返回的是给**模型看**的展示文本 ——
+         * `<stdout>\n83 notes.md\n</stdout>\n\n[exit code: 0]`。
+         * 作者想拿行数就得手工剥这层包装，`split('\n')[0]` 拿到的是字面量
+         * `<stdout>`。这个坑第一次真实迁移就踩到了，而 shell 出去在这批工作流里
+         * 遍地都是（ppt / word / research 全都大量跑脚本）—— 让每个作者各写一遍
+         * 剥壳逻辑，等于把同一个 bug 复制十几份。
+         *
+         * 仍然经 `tool()` 走同一条账本与授权路径，不是旁路。
+         */
+        sh: async (command, opts = {}) => {
+            const raw = (await journaled('tool', `🔧 ${truncate(command, 50)}`, { name: 'Bash', input: { command, ...opts } }, async () => {
+                const toolCallId = `wf-${task}-${randomUUID()}`;
+                const built = buildWorkflowToolContext(ctx, toolCallId, () => undefined);
+                if ('error' in built)
+                    throw new Error(built.error);
+                const exec = ctx.executeTool ?? sdkExecuteTool;
+                const r = await runScheduled('process', truncate(command, 50), () => exec('Bash', JSON.stringify({ command, ...opts }), ctx.signal, built));
+                // ⚠️ 命令**非零退出**不抛异常：shell 的退出码本身常常就是要判断的信息
+                // （`grep -q` 没找到、`test -f` 不存在）。抛不抛由作者看 exitCode 决定。
+                return r.ok
+                    ? r.content
+                    : `<stderr>\n${r.error}\n</stderr>\n\n[exit code: 1]`;
+            }));
+            const pick = (tag) => {
+                const m = new RegExp(`<${tag}>\\n?([\\s\\S]*?)\\n?</${tag}>`).exec(raw);
+                return m ? m[1] : '';
+            };
+            const code = /\[exit code:\s*(-?\d+)\]/.exec(raw);
+            return {
+                stdout: pick('stdout'),
+                stderr: pick('stderr'),
+                exitCode: code ? Number(code[1]) : 0,
+                raw,
+            };
+        },
+        /** HITL 闸门：真停等用户拍板。非交互宿主由 askBridge 自动选推荐项，不挂起。 */
+        ask: async (question, options) => {
+            return journaled('ask', '⏸ 等待用户确认…', { question, options }, async () => {
+                const exec = ctx.executeTool ?? sdkExecuteTool;
+                const r = await runScheduled('tool', '等待用户确认', () => exec('AskUserQuestion', JSON.stringify({
+                    questions: [
+                        {
+                            question: truncate(question, 400),
+                            header: '工作流',
+                            options,
+                        },
+                    ],
+                }), ctx.signal));
+                if (!r.ok)
+                    throw new Error(`提问失败：${r.error}`);
+                // ⚠️ 只解析【答案行】。回执里 Q 行带着问题原文，而问题里常含选项文案 ——
+                // 看整个 content 会把用户选的 A 误判成 B。这是 legacy 踩过的真事故。
+                const answer = r.content
+                    .split('\n')
+                    .map((l) => l.trim())
+                    .filter((l) => /^A\d+[:：]/.test(l))
+                    .join('\n')
+                    .replace(/^A\d+[:：]\s*/, '');
+                return answer;
+            });
+        },
+        /**
+         * 本次运行的资源账本快照。**不进账本** —— 重放要返回**当下**的真实余额，
+         * 而不是上次跑到这里时的旧余额。
+         *
+         * ⚠️ 只在**轮次边界**用它（循环开头判「要不要开下一轮」）。
+         * 不要在一轮进行到一半时拿它中断 —— 产品决策是「宁可超一点预算，
+         * 也不能把 agent 停在半成品状态」，引擎内核也因此完全不做预算检查。
+         *
+         * ⚠️ `trustworthy:false` 表示至少一次调用的 provider 没回报 usage，
+         * 这份账**偏低**。脚本作者要么照常跑（默认），要么明确告知用户，
+         * 但**不要**把它当成「花得少」。
+         */
+        budget: async () => workflowBudget(ctx),
+        /** 确定性检查。**不进账本** —— 重放会返回过期的文件系统事实。 */
+        verify: async (checks) => {
+            const raw = Array.isArray(checks) ? checks : [checks];
+            const parsed = raw.map((c) => ({ raw: c, check: parseCheckString(c) }));
+            // ⚠️ 解析不出来的 check 串必须**响亮报错**。静默丢弃 = 一个拼错的检查项
+            // 让整组验证「通过」，而作者以为自己加了防线 —— 典型的掩耳盗铃。
+            const bad = parsed.filter((p) => p.check === null).map((p) => p.raw);
+            if (bad.length > 0) {
+                throw new Error(`无法解析的检查项：${bad.map((b) => JSON.stringify(b)).join(', ')}。格式是 \`类型:值\`，支持 file_exists / file_contains / shell / test_count。`);
+            }
+            const r = await runVerification(parsed.map((p) => p.check), effectiveWorkflowCwd(ctx));
+            return { passed: r.passed, summary: r.summary, details: r.details };
+        },
+        /** 文件是否存在（相对当前有效 cwd）。不进账本，理由同 verify。 */
+        exists: async (path) => {
+            const check = parseCheckString(`file_exists:${path}`);
+            if (!check)
+                return false;
+            // ⚠️ runVerification 吃的是**数组**（内部 for...of）。传单个对象会抛
+            // `{} is not iterable` —— 这条是端到端实跑抓出来的，不是推理出来的。
+            const r = await runVerification([check], effectiveWorkflowCwd(ctx));
+            return r.passed;
+        },
+        /**
+         * 读文件的**纯文本**（剥掉 Read 工具的行号前缀）。读不到返回 null。
+         *
+         * 为什么单开一个名字：`tool('Read', …)` 返回的是**给模型看**的格式 ——
+         * 每行都带 `<行号><TAB>` 前缀。工作流拿它读 prompt 模板、JSON 数据、
+         * 配置文件时，那些行号是纯噪音：喂给模型浪费 token，喂给 JSON.parse 直接失败。
+         * 和 `sh()` 之于 `tool('Bash')` 是同一件事。
+         *
+         * ⚠️ 剥离规则是 `^\s*\d+\t` —— **分隔符是 TAB 不是箭头**。写错过一次，
+         * 后果是 `readJson()` 对任何文件都静默返回 null（`null?.x` 不报错，
+         * 于是错误一路飘到下游才炸，且报的是「JSON 格式错误或数组为空」，
+         * 而文件其实完全合法）。端到端跑 research 时被抓到。
+         * 已知边界：文件内容里若有某行以「数字 + TAB」开头，那个前缀也会被剥掉。
+         */
+        readText: async (path) => readFileForScript(path),
+        /** 读一个 JSON 文件。读不到或解析失败返回 null（不抛，让脚本自己决定怎么办）。 */
+        readJson: async (path) => {
+            const text = await readFileForScript(path);
+            if (text === null)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+        },
+        /**
+         * 确定性输出给用户：**真正进对话历史**，不烧 LLM、零幻觉。
+         *
+         * ⚠️ 为什么不能只发 `text`（这是实测出来的行为缺陷，不是设计）：
+         * 宿主把 `text` 事件当**流式预览**——TUI 累进 LiveArea、Desktop 累进
+         * `streamingText`——而预览在 `turn_done` 时被清掉，只有 `assistant_message`
+         * 才会落进 `history` / `setMessages`。于是一条纯确定性工作流（只有 echo、
+         * 没有 llm/agent）跑完之后，历史里只剩用户那句 `/workflow xxx`，助手侧一片
+         * 空白，用户完全看不出发生过什么。有 llm 的工作流更糟：中间 agent 的碎话
+         * 留下了，`echo()` 写的最终结论反而没了——恰恰是最该留下的那句。
+         *
+         * 所以这里照 `loop.ts` 的范式办：push 进 `ctx.history` 再 yield
+         * `assistant_message`。两个后果都是想要的：① 两端 UI 立刻正确；
+         * ② 进了 history 就会被 `saveContext` 持久化，重开会话仍在。
+         *
+         * `text` 照发不误——`-p --output-format text/json` 的 `result` 累的是它，
+         * 而 `assistant_message` 在 `print.ts` 里只计 `num_turns`、不进 result
+         * buffer，两者不会重复。
+         */
+        echo: (message) => {
+            const prefix = lastEmittedEndedWithNewline ? '' : '\n';
+            lastEmittedEndedWithNewline = true;
+            emit({ type: 'text', delta: `${prefix}${message}\n` });
+            // ⚠️ 断点续跑的快进段里**不能**再 push：resume 时 history 是从会话文件加载的，
+            // 上一轮写下的这条 echo 已经在里面了，再 push 一次就是重复消息。
+            // 进账本的调用不需要这层判断（`journal.step` 重放时压根不执行 run），
+            // 但 echo 是有意不进账本的（它便宜、无副作用、每次重算）。
+            if (journal.replaying)
+                return;
+            const msg = {
+                role: 'assistant',
+                content: message,
+                id: randomUUID(),
+            };
+            ctx.history.push(msg);
+            emit({ type: 'assistant_message', message: msg });
+        },
+        execFile: async (path, args = [], opts = {}) => journaled('process', `⚙ ${path}`, {
+            path,
+            args,
+            cwd: opts.cwd ?? null,
+            input: opts.input ?? null,
+            timeoutMs: opts.timeoutMs ?? null,
+            env: opts.env ?? null,
+        }, () => runScheduled('process', path, () => executeWorkflowFile(path, args, opts, {
+            cwd: effectiveWorkflowCwd(ctx),
+            workflowDir: workflowDir ?? '',
+            signal: ctx.signal,
+        }))),
+        writeText: async (path, content) => atomicWriteText(effectiveWorkflowCwd(ctx), path, content),
+        writeJson: async (path, value) => atomicWriteJson(effectiveWorkflowCwd(ctx), path, value),
+        mkdir: async (path) => ensureWorkflowDir(effectiveWorkflowCwd(ctx), path),
+        /** Await an explicitly declared child; isolate state while sharing the execution ceiling. */
+        workflow: async (name, inputs = {}, opts = {}) => {
+            if (!deps.invokeWorkflow)
+                throw new Error('当前执行器没有提供子工作流能力');
+            if (typeof name !== 'string' ||
+                !inputs ||
+                typeof inputs !== 'object' ||
+                Array.isArray(inputs))
+                throw new Error('workflow需要工作流名和输入对象');
+            countCall(); // Reserve the shared allowance before starting child side effects.
+            const lane = currentLane();
+            const index = (childCounters.get(lane) ?? 0) + 1;
+            childCounters.set(lane, index);
+            // Always visit the child's state before journal replay: files can disappear
+            // and a child can have finished immediately before its parent was killed.
+            const child = await deps.invokeWorkflow(name, inputs, `${lane}/w${index}`, opts.label);
+            if (!child.reused)
+                journal.markDiverged(lane);
+            return journaled('workflow', opts.label ?? name, { name, inputs, site: `${lane}/w${index}` }, async () => child.value, true);
+        },
+        /**
+         * 无屏障流水线：每项独立走完所有阶段，以确定车道隔离 journal。
+         * 车道 `<父车道>/p<第几个>i<第几项>` 与调度顺序无关；不要用裸 Promise.all
+         * 并发执行同车道的可重放调用。阶段参数为 (prev, item, index)。
+         * 单项失败返回结构化错误，其他项继续；取消必须穿透，不能伪装为普通失败。
+         */
+        pipeline: async (items, options) => {
+            if (!Array.isArray(items)) {
+                throw new Error('pipeline(items, …) 的第一个参数必须是数组');
+            }
+            if (!options || !Array.isArray(options.stages)) {
+                throw new Error('pipeline 第二个参数必须包含 stages 数组');
+            }
+            const stages = options.stages;
+            const concurrency = options.concurrency ?? scope.scheduler.config.pipelineConcurrency;
+            if (!Number.isInteger(concurrency) ||
+                concurrency < 1 ||
+                concurrency > scope.scheduler.config.pipelineMaxConcurrency) {
+                throw new Error(`pipeline concurrency 必须是 1..${scope.scheduler.config.pipelineMaxConcurrency} 的整数`);
+            }
+            const errorMode = options.errorMode ?? 'collect';
+            if (errorMode !== 'collect' && errorMode !== 'fail-fast') {
+                throw new Error('pipeline errorMode 必须是 collect 或 fail-fast');
+            }
+            if (stages.length === 0) {
+                return {
+                    results: items.map((value, index) => ({ ok: true, index, value })),
+                    succeeded: items.length,
+                    failed: 0,
+                };
+            }
+            const parent = currentLane();
+            const blockId = nextPipelineId(parent);
+            const lanes = [];
+            const results = new Array(items.length);
+            let nextIndex = 0;
+            let completed = 0;
+            let succeeded = 0;
+            let failed = 0;
+            let firstFailure;
+            const worker = async () => {
+                while (true) {
+                    if (errorMode === 'fail-fast' && firstFailure)
+                        return;
+                    const index = nextIndex++;
+                    if (index >= items.length)
+                        return;
+                    const item = items[index];
+                    const lane = `${parent}/p${blockId}i${index}`;
+                    lanes.push(lane);
+                    results[index] = await laneStore.run(lane, async () => {
+                        let acc = item;
+                        for (const stage of stages) {
+                            try {
+                                acc = await stage(acc, item, index);
+                            }
+                            catch (e) {
+                                ctx.signal?.throwIfAborted();
+                                if (e instanceof Error && e.name === 'AbortError')
+                                    throw e;
+                                // 该项作废：其后阶段跳过，车道标脏（余下记录不得再被重放冒充）。
+                                journal.markDiverged(lane);
+                                const error = e instanceof Error ? e : new Error(String(e));
+                                firstFailure ??= error;
+                                failed++;
+                                return {
+                                    ok: false,
+                                    index,
+                                    error: structuredWorkflowError(error),
+                                };
+                            }
+                        }
+                        succeeded++;
+                        return { ok: true, index, value: acc };
+                    });
+                    completed++;
+                    emitProgressEvent({
+                        phase: options.label ?? 'pipeline',
+                        status: 'update',
+                        current: completed,
+                        total: items.length,
+                        succeeded,
+                        failed,
+                        message: `${options.label ?? 'pipeline'} ${completed}/${items.length}`,
+                    });
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+            // 任一子车道分叉 → 污染父车道：下游串行步骤依赖扇出的聚合结果，
+            // 上游变了就不能再拿旧结果冒充。
+            if (lanes.some((l) => journal.laneDiverged(l))) {
+                journal.markDiverged(parent);
+            }
+            if (errorMode === 'fail-fast' && firstFailure) {
+                throw new AggregateError([firstFailure], `${options.label ?? 'pipeline'} 在第一个失败项后停止调度：${firstFailure.message}`);
+            }
+            return { results, succeeded, failed };
+        },
+        structuredProgress: (update) => {
+            emitProgressEvent(update);
+            if (typeof update.message === 'string' && update.message.trim()) {
+                void state
+                    .appendProgress(`ℹ ${update.message.trim()}`)
+                    .catch(() => undefined);
+            }
+        },
+        log: (message) => {
+            progress(message);
+            // log() is intentionally non-blocking for workflow authors, but retain
+            // the same evidence on disk as the transient plugin_progress event.
+            // The UI can be cleared; progress.md is what post-mortem diagnostics use.
+            void state.appendProgress(`ℹ ${message}`).catch(() => undefined);
+        },
+        /**
+         * 运行时追加一条产物声明。
+         *
+         * `meta.artifacts` 是执行前静态解析的纯字面量，写不出 `out/${session}/page-3.png`
+         * 这种带循环下标的路径 —— 循环体里的逐迭代产物只能在这里登记。不登记的后果是
+         * new-task 清理漏掉它们、completed 少报产物，且**表现为静默漏档而不是报错**。
+         */
+        declareArtifact: (path) => {
+            ctx.declaredArtifacts?.add(path);
+            emitProgressEvent({
+                phase: 'artifact',
+                status: 'update',
+                message: `登记产物：${path}`,
+            });
+        },
+        /** 追加一条用户补充要求，与原始目标同等贯穿后续每次调用。 */
+        addGoalSupplement: async (text) => {
+            const t = String(text ?? '').trim();
+            if (!t)
+                return;
+            ctx.goalSupplements ??= [];
+            if (!ctx.goalSupplements.includes(t))
+                ctx.goalSupplements.push(t);
+            await state.appendSupplement(t);
+        },
+        /** 让具体工作流把确认后的契约交回其外层控制器；Runner 不解释契约内容。 */
+        syncManagedContract: async (input) => {
+            if (!ctx.managedBridge) {
+                throw new Error('syncManagedContract 只能在外层运行时管理的工作流中使用');
+            }
+            const update = await ctx.managedBridge.updateContract(input);
+            if (ctx.managedExecution) {
+                ctx.managedExecution.version = update.version;
+                ctx.managedExecution.anchor = update.anchor;
+            }
+            return update.value;
+        },
+    };
+    const wf = {
+        input: Object.freeze({ values: args, resources: deps.inputResourceMap ?? {} }),
+        runtime: Object.freeze({
+            workflowName: deps.workflowName,
+            workflowDir: workflowDir ?? '',
+            cwd: effectiveWorkflowCwd(ctx),
+            sessionId: session,
+            taskId: task,
+            runId,
+            rootRunId: scope.rootRunId,
+            goal: ctx.goalAnchor ?? '',
+        }),
+        model: Object.freeze({
+            generate: capabilities.llm,
+            agent: capabilities.agent,
+            skill: capabilities.skill,
+            require: capabilities.requireModel,
+        }),
+        tools: Object.freeze({ call: capabilities.tool, callResult: capabilities.toolResult }),
+        exec: Object.freeze({ shell: capabilities.sh, file: capabilities.execFile }),
+        fs: Object.freeze({
+            exists: capabilities.exists,
+            readText: capabilities.readText,
+            readJson: capabilities.readJson,
+            writeText: capabilities.writeText,
+            writeJson: capabilities.writeJson,
+            mkdir: capabilities.mkdir,
+        }),
+        flow: Object.freeze({
+            pipeline: capabilities.pipeline,
+            child: capabilities.workflow,
+            ask: capabilities.ask,
+        }),
+        check: Object.freeze({ verify: capabilities.verify }),
+        state: Object.freeze({
+            budget: capabilities.budget,
+            resetModelContext: capabilities.resetContext,
+            addGoalSupplement: capabilities.addGoalSupplement,
+            syncManagedContract: capabilities.syncManagedContract,
+        }),
+        output: Object.freeze({
+            message: capabilities.echo,
+            progress: capabilities.structuredProgress,
+            artifact: capabilities.declareArtifact,
+        }),
+    };
+    assertWorkflowContextShape(wf);
+    return Object.freeze(wf);
+}