minimal-agent 0.12.0 → 0.14.0

package/plugins/workflow-runner/src/stepExecutors/set.js

@@ -1,49 +0,0 @@
-/**
- * ============================================================
- *  stepExecutors/set.ts —— 确定性变量赋值
- * ------------------------------------------------------------
- *  从 `runner.ts::runSteps` 的内联块搬出来。搬出来的收益不只是「runner 短了 40 行」：
- *  它现在走**统一的提交流水线**（`stepPipeline.ts::commitStep`），于是
- *  **`capture:` 自然生效了** —— 此前 set 从不调 `bindCapture`、checkpoint 里
- *  记的是 `resolved` 而非 `collectCaptured(...)`，yaml 作者写了 `capture` 既不
- *  报错也不生效，resume 时也回放不出来。典型的静默失效。
- *
- *  ⚠️ 两个必须保住的语义：
- *   ① 写的是 `vars.setGlobal`（根帧）不是 `vars.set` —— set 步声明的是**工作流级**
- *     变量，在循环体里写也必须活到循环之外。
- *   ② 顶层值若是单一 `"${EXPR}"` 模板走 `interpolateTyped` **保留类型**
- *     （布尔/数字/数组不字符串化成 "true"，下游条件不必写 `== true || == 'true'` 防御）；
- *     多片段模板与嵌套结构走 `interpolateDeep`，行为不变。
- * ============================================================
- */
-import { interpolateDeep, interpolateTyped } from '../expressions.js';
-export async function* execSetStep(step, vars) {
-    const missing = [];
-    const resolved = {};
-    for (const [k, v] of Object.entries(step.set ?? {})) {
-        resolved[k] =
-            typeof v === 'string'
-                ? interpolateTyped(v, vars, { onMissing: (e) => missing.push(e) })
-                : interpolateDeep(v, vars, { onMissing: (e) => missing.push(e) });
-    }
-    if (missing.length > 0) {
-        yield {
-            type: 'warning',
-            message: `step "${step.id}": 模板变量未定义：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-        };
-    }
-    for (const [k, v] of Object.entries(resolved)) {
-        vars.setGlobal(k, v);
-    }
-    const summary = Object.entries(resolved)
-        .map(([k, v]) => `${k}=${String(v).slice(0, 40)}`)
-        .join(', ');
-    // raw 就是赋值表本身 —— 这样 `capture: { <变量名>: <别名> }` 能取到刚赋的值。
-    // replayVars 让 checkpoint 记下这些赋值：resume 跳过本步时变量仍能回放
-    //（set 步通常没有 capture:，只靠 collectCaptured 会记成 {}）。
-    return {
-        raw: { ...resolved },
-        replayVars: { ...resolved },
-        preview: `set: ${summary}`,
-    };
-}

package/plugins/workflow-runner/src/stepExecutors/set.ts

@@ -1,56 +0,0 @@
-/**
- * ============================================================
- *  stepExecutors/set.ts —— 确定性变量赋值
- * ------------------------------------------------------------
- *  从 `runner.ts::runSteps` 的内联块搬出来。搬出来的收益不只是「runner 短了 40 行」：
- *  它现在走**统一的提交流水线**（`stepPipeline.ts::commitStep`），于是
- *  **`capture:` 自然生效了** —— 此前 set 从不调 `bindCapture`、checkpoint 里
- *  记的是 `resolved` 而非 `collectCaptured(...)`，yaml 作者写了 `capture` 既不
- *  报错也不生效，resume 时也回放不出来。典型的静默失效。
- *
- *  ⚠️ 两个必须保住的语义：
- *   ① 写的是 `vars.setGlobal`（根帧）不是 `vars.set` —— set 步声明的是**工作流级**
- *     变量，在循环体里写也必须活到循环之外。
- *   ② 顶层值若是单一 `"${EXPR}"` 模板走 `interpolateTyped` **保留类型**
- *     （布尔/数字/数组不字符串化成 "true"，下游条件不必写 `== true || == 'true'` 防御）；
- *     多片段模板与嵌套结构走 `interpolateDeep`，行为不变。
- * ============================================================
- */
-
-import type { LoopEvent } from '../../../../src/plugin-sdk.js';
-import { interpolateDeep, interpolateTyped } from '../expressions.js';
-import type { StepDef, StepResult, VarStack } from '../types.js';
-
-export async function* execSetStep(
-  step: StepDef,
-  vars: VarStack,
-): AsyncGenerator<LoopEvent, StepResult, void> {
-  const missing: string[] = [];
-  const resolved: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(step.set ?? {})) {
-    resolved[k] =
-      typeof v === 'string'
-        ? interpolateTyped(v, vars, { onMissing: (e) => missing.push(e) })
-        : interpolateDeep(v, vars, { onMissing: (e) => missing.push(e) });
-  }
-  if (missing.length > 0) {
-    yield {
-      type: 'warning',
-      message: `step "${step.id}": 模板变量未定义：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-    } as LoopEvent;
-  }
-  for (const [k, v] of Object.entries(resolved)) {
-    vars.setGlobal(k, v);
-  }
-  const summary = Object.entries(resolved)
-    .map(([k, v]) => `${k}=${String(v).slice(0, 40)}`)
-    .join(', ');
-  // raw 就是赋值表本身 —— 这样 `capture: { <变量名>: <别名> }` 能取到刚赋的值。
-  // replayVars 让 checkpoint 记下这些赋值：resume 跳过本步时变量仍能回放
-  //（set 步通常没有 capture:，只靠 collectCaptured 会记成 {}）。
-  return {
-    raw: { ...resolved },
-    replayVars: { ...resolved },
-    preview: `set: ${summary}`,
-  };
-}

package/plugins/workflow-runner/src/stepExecutors/skill.js

@@ -1,111 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill 步骤执行器
- * ------------------------------------------------------------
- *  v0.9 重构：不再使用独立 subHistory 隔离子循环，而是委托主 TAOR 引擎
- *  （runQuery / src/loop.ts）在共享 ctx.history 上执行。
- *
- *  实现要点：
- *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback
- *    - SKILL.md body 作为用户提示的一部分（系统提示词已在 history[0]）
- *    - 执行结果直接写入共享 ctx.history，上下文自然积累
- *    - 流式转发：runQuery yield 的事件直接透传给 UI
- *    - maxTurns 可在 step 里覆盖（默认 25）
- *
- *  capture：{ text: var_name } / { result: var_name }
- * ============================================================
- */
-import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getResourceSearchPaths, } from '../../../../src/plugin-sdk.js';
-import { describeLlmFailure, describeMaxTurnsCutoff, effectiveGoalAnchor, runStepQuery, } from '../agentCommon.js';
-import { interpolate } from '../expressions.js';
-import { effectiveWorkflowCwd } from '../toolRuntime.js';
-function stripFrontmatter(content) {
-    return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
-}
-function parseFrontmatterName(content) {
-    const m = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!m)
-        return null;
-    const nm = m[1].match(/^name:\s*(.+)$/m);
-    if (!nm)
-        return null;
-    return nm[1].trim().replace(/^["']|["']$/g, '');
-}
-async function findSkillFile(skillName, cwd) {
-    const roots = getResourceSearchPaths('skills', import.meta.url, cwd);
-    for (const root of roots) {
-        let entries;
-        try {
-            entries = await readdir(root, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const e of entries) {
-            if (!e.isDirectory())
-                continue;
-            const skillFile = join(root, e.name, 'SKILL.md');
-            if (e.name === skillName)
-                return skillFile;
-            try {
-                const md = await readFile(skillFile, 'utf8');
-                if (parseFrontmatterName(md) === skillName)
-                    return skillFile;
-            }
-            catch { }
-        }
-    }
-    return null;
-}
-export async function* execSkillStep(step, vars, ctx) {
-    if (!step.skill)
-        throw new Error(`step ${step.id}: 缺少 skill 字段`);
-    const skillName = interpolate(step.skill, vars);
-    const skillFile = await findSkillFile(skillName, effectiveWorkflowCwd(ctx));
-    if (!skillFile) {
-        throw new Error(`step ${step.id}: 未找到 skill "${skillName}"（cwd/skills/ 与 packageRoot/skills/ 双源均未命中）`);
-    }
-    const md = await readFile(skillFile, 'utf8');
-    const body = stripFrontmatter(md).trim();
-    // 构造用户提示：skill 指令 + 步骤 input
-    // 系统提示词已在 history[0] 中（含完整 skill 列表和描述），
-    // 这里不需要再拼 system message——把 SKILL.md body 作为操作指令即可
-    const missing = [];
-    const userInput = step.input
-        ? interpolate(step.input, vars, { onMissing: (e) => missing.push(e) })
-        : `请按以下 SKILL "${skillName}" 的指示完成任务。`;
-    const fullPrompt = `【执行 Skill：${skillName}】\n\n${body}\n\n---\n\n当前任务：\n${userInput}`;
-    // 通用目标锚定（原始目标 + 补充要求）：确保 skill 执行时也不偏离
-    const anchor = effectiveGoalAnchor(ctx);
-    const effectivePrompt = anchor ? `${anchor}\n\n${fullPrompt}` : fullPrompt;
-    const maxTurns = step.maxTurns ?? 25;
-    if (missing.length > 0) {
-        yield {
-            type: 'warning',
-            message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-        };
-    }
-    // 委托 TAOR 引擎在共享 history 上执行（共享消费层 runStepQuery）。
-    // suppressTurnDone：turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结，
-    // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
-    const { rawText, aborted, sawLlmError, sawMaxTurns, llmErrorDetail } = yield* runStepQuery(effectivePrompt, step, ctx, {
-        maxTurns,
-        suppressTurnDone: true,
-    });
-    const trimmed = rawText.trim();
-    // P0-1：LLM 失败（超时/网络错）且本步无任何产出 → 抛异常，触发 runner 的 max_retries 重跑。
-    // 用户中断（aborted）不该被当成可重试失败，按现状返回空结果即可。
-    if (!trimmed && sawLlmError && !aborted) {
-        throw new Error(describeLlmFailure(step.id, llmErrorDetail));
-    }
-    // 撞 maxTurns 截断 → 截断时产出不可信，抛可重试失败（续作语义，同 agent.ts）
-    if (sawMaxTurns && !aborted) {
-        throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
-    }
-    return {
-        raw: { text: trimmed, result: trimmed },
-        preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,
-    };
-}

package/plugins/workflow-runner/src/stepExecutors/skill.ts

@@ -1,140 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill 步骤执行器
- * ------------------------------------------------------------
- *  v0.9 重构：不再使用独立 subHistory 隔离子循环，而是委托主 TAOR 引擎
- *  （runQuery / src/loop.ts）在共享 ctx.history 上执行。
- *
- *  实现要点：
- *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback
- *    - SKILL.md body 作为用户提示的一部分（系统提示词已在 history[0]）
- *    - 执行结果直接写入共享 ctx.history，上下文自然积累
- *    - 流式转发：runQuery yield 的事件直接透传给 UI
- *    - maxTurns 可在 step 里覆盖（默认 25）
- *
- *  capture：{ text: var_name } / { result: var_name }
- * ============================================================
- */
-
-import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-
-import {
-  type LoopEvent,
-  getResourceSearchPaths,
-} from '../../../../src/plugin-sdk.js';
-import {
-  describeLlmFailure,
-  describeMaxTurnsCutoff,
-  effectiveGoalAnchor,
-  runStepQuery,
-} from '../agentCommon.js';
-import { interpolate } from '../expressions.js';
-import { effectiveWorkflowCwd } from '../toolRuntime.js';
-import type { RunContext, StepDef, StepResult, VarStack } from '../types.js';
-
-function stripFrontmatter(content: string): string {
-  return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
-}
-
-function parseFrontmatterName(content: string): string | null {
-  const m = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!m) return null;
-  const nm = m[1].match(/^name:\s*(.+)$/m);
-  if (!nm) return null;
-  return nm[1].trim().replace(/^["']|["']$/g, '');
-}
-
-async function findSkillFile(
-  skillName: string,
-  cwd: string,
-): Promise<string | null> {
-  const roots = getResourceSearchPaths('skills', import.meta.url, cwd);
-
-  for (const root of roots) {
-    let entries: { name: string; isDirectory: () => boolean }[];
-    try {
-      entries = await readdir(root, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      const skillFile = join(root, e.name, 'SKILL.md');
-      if (e.name === skillName) return skillFile;
-      try {
-        const md = await readFile(skillFile, 'utf8');
-        if (parseFrontmatterName(md) === skillName) return skillFile;
-      } catch {}
-    }
-  }
-  return null;
-}
-
-export async function* execSkillStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): AsyncGenerator<LoopEvent, StepResult, void> {
-  if (!step.skill) throw new Error(`step ${step.id}: 缺少 skill 字段`);
-  const skillName = interpolate(step.skill, vars);
-
-  const skillFile = await findSkillFile(skillName, effectiveWorkflowCwd(ctx));
-  if (!skillFile) {
-    throw new Error(
-      `step ${step.id}: 未找到 skill "${skillName}"（cwd/skills/ 与 packageRoot/skills/ 双源均未命中）`,
-    );
-  }
-  const md = await readFile(skillFile, 'utf8');
-  const body = stripFrontmatter(md).trim();
-
-  // 构造用户提示：skill 指令 + 步骤 input
-  // 系统提示词已在 history[0] 中（含完整 skill 列表和描述），
-  // 这里不需要再拼 system message——把 SKILL.md body 作为操作指令即可
-  const missing: string[] = [];
-  const userInput = step.input
-    ? interpolate(step.input, vars, { onMissing: (e) => missing.push(e) })
-    : `请按以下 SKILL "${skillName}" 的指示完成任务。`;
-
-  const fullPrompt = `【执行 Skill：${skillName}】\n\n${body}\n\n---\n\n当前任务：\n${userInput}`;
-
-  // 通用目标锚定（原始目标 + 补充要求）：确保 skill 执行时也不偏离
-  const anchor = effectiveGoalAnchor(ctx);
-  const effectivePrompt = anchor ? `${anchor}\n\n${fullPrompt}` : fullPrompt;
-
-  const maxTurns = step.maxTurns ?? 25;
-
-  if (missing.length > 0) {
-    yield {
-      type: 'warning',
-      message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-    };
-  }
-
-  // 委托 TAOR 引擎在共享 history 上执行（共享消费层 runStepQuery）。
-  // suppressTurnDone：turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结，
-  // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
-  const { rawText, aborted, sawLlmError, sawMaxTurns, llmErrorDetail } =
-    yield* runStepQuery(effectivePrompt, step, ctx, {
-      maxTurns,
-      suppressTurnDone: true,
-    });
-
-  const trimmed = rawText.trim();
-
-  // P0-1：LLM 失败（超时/网络错）且本步无任何产出 → 抛异常，触发 runner 的 max_retries 重跑。
-  // 用户中断（aborted）不该被当成可重试失败，按现状返回空结果即可。
-  if (!trimmed && sawLlmError && !aborted) {
-    throw new Error(describeLlmFailure(step.id, llmErrorDetail));
-  }
-
-  // 撞 maxTurns 截断 → 截断时产出不可信，抛可重试失败（续作语义，同 agent.ts）
-  if (sawMaxTurns && !aborted) {
-    throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
-  }
-
-  return {
-    raw: { text: trimmed, result: trimmed },
-    preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,
-  };
-}

package/plugins/workflow-runner/src/stepExecutors/tool.js

@@ -1,208 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/tool.ts —— tool step 执行
- * ------------------------------------------------------------
- *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
- *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
- *
- *  v2（P1 TUI 可见）：本执行器改为 AsyncGenerator，在调 executeTool 前后
- *  yield 通用 tool_start / tool_end LoopEvent —— 这样 workflow 的 tool 步骤
- *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述）。
- *
- *  v0.9.3（上下文统一修复）：tool 步骤执行后把工具调用摘要写入 ctx.history，
- *  让后续 agent/llm/skill 步骤（走 runQuery → LLM）能自然看到前面步骤的工作成果，
- *  不再依赖 VarStack 变量插值作为唯一的信息传递通道。
- *  这实现了"一套上下文"架构：workflow 的每一步都在共享的 TAOR history 中留痕。
- *
- *  capture 字段（支持点路径）：
- *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
- *    - `{ result: var_name }`       同义，给"无结构化字段"工具用
- *    - `{ args.content: var_name }` 绑插值后传给工具的入参（如真正写入的内容）
- *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
- * ============================================================
- */
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { executeTool, getToolByName, recordRead, } from '../../../../src/plugin-sdk.js';
-import { interpolateDeep } from '../expressions.js';
-import { buildWorkflowToolContext, effectiveWorkflowCwd, } from '../toolRuntime.js';
-export async function* execToolStep(step, vars, ctx) {
-    if (!step.tool)
-        throw new Error(`step ${step.id}: 缺少 tool 字段`);
-    const tool = getToolByName(step.tool);
-    if (!tool)
-        throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
-    if (!ctx.tools.some((available) => available.name === tool.name)) {
-        throw new Error(`step ${step.id}: 工具 "${tool.name}" 不在当前宿主授权的 Workflow 工具集中`);
-    }
-    // 未定义变量插值可见化（args 里静默空串会让工具拿到空路径/空内容）
-    const missing = [];
-    const args = interpolateDeep(step.args ?? {}, vars, {
-        onMissing: (e) => missing.push(e),
-    });
-    if (missing.length > 0) {
-        yield {
-            type: 'warning',
-            message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
-        };
-    }
-    const argsJson = JSON.stringify(args);
-    const toolCallId = `wf_${step.id}`;
-    const argsPreview = argsJson.length > 80 ? `${argsJson.slice(0, 80)}…` : argsJson;
-    yield {
-        type: 'tool_start',
-        toolName: tool.name,
-        toolCallId,
-        argsPreview,
-        argsFriendly: friendlyToolDesc(tool.name, args),
-    };
-    // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
-    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
-    // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
-    // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
-    // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
-    // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
-    // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
-    await preReadDeclaredArtifact(tool, args, step, ctx);
-    // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
-    // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
-    const pendingProgress = [];
-    let wakeProgress;
-    const toolContext = buildWorkflowToolContext(step, ctx, toolCallId, (message, detail) => {
-        pendingProgress.push({
-            type: 'tool_progress',
-            toolName: tool.name,
-            toolCallId,
-            message,
-            detail,
-        });
-        wakeProgress?.();
-    });
-    if ('error' in toolContext) {
-        throw new Error(`step ${step.id}: ${toolContext.error}`);
-    }
-    const dispatch = ctx.executeTool ?? executeTool;
-    let settled = false;
-    let result;
-    void dispatch(tool.name, argsJson, ctx.signal, toolContext)
-        .then((value) => {
-        result = value;
-    })
-        .catch((error) => {
-        result = {
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-        };
-    })
-        .finally(() => {
-        settled = true;
-        wakeProgress?.();
-    });
-    while (!settled || pendingProgress.length > 0) {
-        const progress = pendingProgress.shift();
-        if (progress) {
-            yield progress;
-            continue;
-        }
-        await new Promise((resolveWake) => {
-            wakeProgress = resolveWake;
-            if (settled || pendingProgress.length > 0)
-                resolveWake();
-        });
-        wakeProgress = undefined;
-    }
-    if (!result)
-        throw new Error(`step ${step.id}: 工具执行未返回结果`);
-    yield {
-        type: 'tool_end',
-        toolName: tool.name,
-        toolCallId,
-        ok: result.ok,
-        content: result.ok ? result.content : result.error,
-        metadata: result.metadata,
-    };
-    if (!result.ok) {
-        throw new Error(result.error);
-    }
-    const content = result.content;
-    // ════ v0.9.3：上下文统一 —— 把工具调用写入共享 history ════
-    // 后续 agent/llm/skill 步骤走 runQuery() 时，LLM 能在上下文中看到
-    // 这步做了什么（与正常 TAOR 循环中 tool_call → tool_result 的记录方式一致）。
-    // 只记录精简摘要（不把完整工具回执塞入 history，避免 token 浪费）。
-    const summary = content.length > 500
-        ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
-        : content;
-    ctx.history.push({
-        role: 'assistant',
-        content: `[workflow:${step.id}] ✅ ${tool.name} 执行完成：${summary}`,
-        timestamp: Date.now(),
-        id: crypto.randomUUID(),
-    });
-    // ⚠️ 工具返回的图片**不能丢**。此前这里只取 content，`visionImages` 被静默丢弃 ——
-    // 于是任何「截图/看图」类工作流都拿不到产物，而且不会报错，只是后面的评估步没图可看。
-    // 取路径而不是整个 ImageInputSpec：yaml 侧要的是能 capture、能传给 llm 步 `images:`
-    // 的字符串；结构体传下去反而要每个消费方各自解包。
-    const images = (result.visionImages ?? [])
-        .map((image) => (typeof image.source === 'string' ? image.source : ''))
-        .filter((path) => path.length > 0);
-    return {
-        raw: {
-            content,
-            result: content,
-            args,
-            images,
-            metadata: result.metadata,
-            recovery: result.recovery,
-            sensitivity: result.sensitivity,
-            visionNote: result.visionNote,
-        },
-        preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
-    };
-}
-/**
- * 写类 tool 步的目标文件若命中声明产物且已存在 → pre-Read 解除内核守卫。
- *
- * 路径归一化：artifacts 声明相对 cwd；args.file_path 可能是 ./相对 或 绝对，
- * 双方都 resolve(cwd, …) 后比较（win32 文件系统大小写不敏感 → lowercase 比较；
- * 其余平台保持大小写敏感，避免 Plan.md / plan.md 误判同文件）。
- */
-async function preReadDeclaredArtifact(tool, args, step, ctx) {
-    if (tool.isReadOnly !== false)
-        return; // 只对写类工具生效
-    if (typeof args.file_path !== 'string')
-        return;
-    const norm = (p) => {
-        const abs = resolve(effectiveWorkflowCwd(ctx), p);
-        return process.platform === 'win32' ? abs.toLowerCase() : abs;
-    };
-    const target = norm(args.file_path);
-    const declared = [
-        ...(ctx.declaredArtifacts ?? []),
-        ...(step.artifacts ?? []),
-    ];
-    if (!declared.some((a) => norm(a) === target))
-        return;
-    const abs = resolve(effectiveWorkflowCwd(ctx), args.file_path);
-    if (!existsSync(abs))
-        return; // 新建文件不需要解守卫
-    // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
-    //   1. 声明产物本就要被本步整体覆盖，旧内容无需进上下文/烧 token；
-    //   2. 真 Read 大文件会触发字符上限截断（read.ts → recordRead({truncated:true})），
-    //      反而踩中 Write 的「截断禁写」硬守卫（write.ts: existsSync && wasTruncated → 拒绝），
-    //      正是本步要解除的同一道墙——曾导致 plan.yaml 回写变长的 PLAN.md 时 halt
-    //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
-    //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
-    // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
-    recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
-}
-/**
- * 给 tool_start 生成人话描述（LiveArea spinner 行用）。
- */
-function friendlyToolDesc(toolName, args) {
-    const key = ['file_path', 'command', 'query', 'pattern', 'path', 'url'].find((k) => typeof args[k] === 'string');
-    if (!key)
-        return toolName;
-    const val = String(args[key]);
-    const short = val.length > 60 ? `${val.slice(0, 60)}…` : val;
-    return `${toolName} ${short}`;
-}