minimal-agent 0.11.0 → 0.12.0

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

@@ -25,6 +25,7 @@ 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 字段`);
@@ -56,8 +57,8 @@ export async function* execToolStep(step, vars, ctx) {
         argsFriendly: friendlyToolDesc(tool.name, args),
     };
     // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
-    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 进程级 Map，
-    // 跨进程 / resume / 残留旧产物时必空）。确定性 tool 步的 args 是 yaml 作者
+    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
+    // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
     // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
     // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
     // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
@@ -65,16 +66,60 @@ export async function* execToolStep(step, vars, ctx) {
     await preReadDeclaredArtifact(tool, args, step, ctx);
     // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
     // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
-    const hostSlice = hostContextFor(step, ctx);
-    if ('error' in hostSlice)
-        throw new Error(`step ${step.id}: ${hostSlice.error}`);
-    const result = await executeTool(tool.name, argsJson, ctx.signal, hostSlice.ctx);
+    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);
@@ -101,56 +146,19 @@ export async function* execToolStep(step, vars, ctx) {
         .map((image) => (typeof image.source === 'string' ? image.source : ''))
         .filter((path) => path.length > 0);
     return {
-        raw: { content, result: content, args, images },
+        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,
     };
 }
-/**
- * 按 `step.uses` 从宿主上下文里切出这一步该拿到的那片。
- *
- * 三条语义，缺一条这个机制就退化：
- *   · 未声明 `uses` → 返回**空上下文**（不是 undefined，`toolGate` 这类与能力无关的
- *     宿主策略仍要生效）。工具因此走自己的清晰报错，不会静默降级；
- *   · 声明了但宿主没提供 → **响亮报错**。yaml 说了要用电脑，而这次运行根本没开
- *     `--computer-use`，那是配置错误，应该在这一步就停，不是跑到一半才发现；
- *   · 只转发声明过的那一片 —— 声明 `[computer]` 的步拿不到 `browserRun`。
- *
- * 单一出处：切片逻辑只在这里，runner / 其它 executor 都不许自己拼。
- */
-function hostContextFor(step, ctx) {
-    // toolGate 是宿主的通用策略缝（与具体能力无关），任何步都该受它约束。
-    const base = ctx.host?.toolGate
-        ? { toolGate: ctx.host.toolGate }
-        : {};
-    const uses = step.uses ?? [];
-    if (uses.length === 0)
-        return { ctx: base };
-    const out = { ...base };
-    for (const capability of uses) {
-        if (capability === 'computer') {
-            if (!ctx.host?.computerRun) {
-                return {
-                    error: 'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— '
-                        + '请用 `--computer-use interactive` 启动，或去掉该步的 uses 声明。',
-                };
-            }
-            out.computerRun = ctx.host.computerRun;
-            // 人工接管通道与能力同进退：没有它，遇到验证/密码只能硬失败。
-            if (ctx.host.computerIntervention)
-                out.computerIntervention = ctx.host.computerIntervention;
-        }
-        else if (capability === 'browser') {
-            if (!ctx.host?.browserRun) {
-                return {
-                    error: 'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。'
-                        + '（基础浏览操作不声明 uses 也能用；upload/submit 这类才需要它。）',
-                };
-            }
-            out.browserRun = ctx.host.browserRun;
-        }
-    }
-    return { ctx: out };
-}
 /**
  * 写类 tool 步的目标文件若命中声明产物且已存在 → pre-Read 解除内核守卫。
  *
@@ -164,14 +172,17 @@ async function preReadDeclaredArtifact(tool, args, step, ctx) {
     if (typeof args.file_path !== 'string')
         return;
     const norm = (p) => {
-        const abs = resolve(ctx.cwd, 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 ?? [])];
+    const declared = [
+        ...(ctx.declaredArtifacts ?? []),
+        ...(step.artifacts ?? []),
+    ];
     if (!declared.some((a) => norm(a) === target))
         return;
-    const abs = resolve(ctx.cwd, args.file_path);
+    const abs = resolve(effectiveWorkflowCwd(ctx), args.file_path);
     if (!existsSync(abs))
         return; // 新建文件不需要解守卫
     // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
@@ -182,7 +193,7 @@ async function preReadDeclaredArtifact(tool, args, step, ctx) {
     //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
     //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
     // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
-    recordRead(abs, { truncated: false });
+    recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
 }
 /**
  * 给 tool_start 生成人话描述（LiveArea spinner 行用）。

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

@@ -26,13 +26,17 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import {
+  type LoopEvent,
+  type ToolResult,
   executeTool,
   getToolByName,
   recordRead,
-  type LoopEvent,
-  type ToolCallContext,
 } from '../../../../src/plugin-sdk.js';
 import { interpolateDeep } from '../expressions.js';
+import {
+  buildWorkflowToolContext,
+  effectiveWorkflowCwd,
+} from '../toolRuntime.js';
 import type { RunContext, StepDef, StepResult, VarStack } from '../types.js';
 
 export async function* execToolStep(
@@ -74,19 +78,73 @@ export async function* execToolStep(
   };
 
   // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
-  // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 进程级 Map，
-  // 跨进程 / resume / 残留旧产物时必空）。确定性 tool 步的 args 是 yaml 作者
+  // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 按会话隔离，
+  // 跨进程 / resume / 残留旧产物时可能为空）。确定性 tool 步的 args 是 yaml 作者
   // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
   // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
   // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
   // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
-  await preReadDeclaredArtifact(tool, args as Record<string, unknown>, step, ctx);
+  await preReadDeclaredArtifact(
+    tool,
+    args as Record<string, unknown>,
+    step,
+    ctx,
+  );
 
   // 宿主能力按 `uses:` 切片后转发。`executeTool` 的第四参此前从未传过 ——
   // 这正是「workflow 里 ComputerUse 恒失败」的末端表现。
-  const hostSlice = hostContextFor(step, ctx);
-  if ('error' in hostSlice) throw new Error(`step ${step.id}: ${hostSlice.error}`);
-  const result = await executeTool(tool.name, argsJson, ctx.signal, hostSlice.ctx);
+  const pendingProgress: LoopEvent[] = [];
+  let wakeProgress: (() => void) | undefined;
+  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: ToolResult | undefined;
+  void dispatch(tool.name, argsJson, ctx.signal, toolContext)
+    .then((value) => {
+      result = value;
+    })
+    .catch((error: unknown) => {
+      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<void>((resolveWake) => {
+      wakeProgress = resolveWake;
+      if (settled || pendingProgress.length > 0) resolveWake();
+    });
+    wakeProgress = undefined;
+  }
+  if (!result) throw new Error(`step ${step.id}: 工具执行未返回结果`);
 
   yield {
     type: 'tool_end',
@@ -94,6 +152,7 @@ export async function* execToolStep(
     toolCallId,
     ok: result.ok,
     content: result.ok ? result.content : result.error,
+    metadata: result.metadata,
   };
 
   if (!result.ok) {
@@ -105,9 +164,10 @@ export async function* execToolStep(
   // 后续 agent/llm/skill 步骤走 runQuery() 时，LLM 能在上下文中看到
   // 这步做了什么（与正常 TAOR 循环中 tool_call → tool_result 的记录方式一致）。
   // 只记录精简摘要（不把完整工具回执塞入 history，避免 token 浪费）。
-  const summary = content.length > 500
-    ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
-    : content;
+  const summary =
+    content.length > 500
+      ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
+      : content;
   ctx.history.push({
     role: 'assistant',
     content: `[workflow:${step.id}] ✅ ${tool.name} 执行完成：${summary}`,
@@ -124,61 +184,20 @@ export async function* execToolStep(
     .filter((path) => path.length > 0);
 
   return {
-    raw: { content, result: content, args, images },
+    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,
   };
 }
 
-/**
- * 按 `step.uses` 从宿主上下文里切出这一步该拿到的那片。
- *
- * 三条语义，缺一条这个机制就退化：
- *   · 未声明 `uses` → 返回**空上下文**（不是 undefined，`toolGate` 这类与能力无关的
- *     宿主策略仍要生效）。工具因此走自己的清晰报错，不会静默降级；
- *   · 声明了但宿主没提供 → **响亮报错**。yaml 说了要用电脑，而这次运行根本没开
- *     `--computer-use`，那是配置错误，应该在这一步就停，不是跑到一半才发现；
- *   · 只转发声明过的那一片 —— 声明 `[computer]` 的步拿不到 `browserRun`。
- *
- * 单一出处：切片逻辑只在这里，runner / 其它 executor 都不许自己拼。
- */
-function hostContextFor(
-  step: StepDef,
-  ctx: RunContext,
-): { ctx: ToolCallContext } | { error: string } {
-  // toolGate 是宿主的通用策略缝（与具体能力无关），任何步都该受它约束。
-  const base: ToolCallContext = ctx.host?.toolGate
-    ? { toolGate: ctx.host.toolGate }
-    : {};
-  const uses = step.uses ?? [];
-  if (uses.length === 0) return { ctx: base };
-
-  const out: ToolCallContext = { ...base };
-  for (const capability of uses) {
-    if (capability === 'computer') {
-      if (!ctx.host?.computerRun) {
-        return {
-          error:
-            'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— '
-            + '请用 `--computer-use interactive` 启动，或去掉该步的 uses 声明。',
-        };
-      }
-      out.computerRun = ctx.host.computerRun;
-      // 人工接管通道与能力同进退：没有它，遇到验证/密码只能硬失败。
-      if (ctx.host.computerIntervention) out.computerIntervention = ctx.host.computerIntervention;
-    } else if (capability === 'browser') {
-      if (!ctx.host?.browserRun) {
-        return {
-          error:
-            'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。'
-            + '（基础浏览操作不声明 uses 也能用；upload/submit 这类才需要它。）',
-        };
-      }
-      out.browserRun = ctx.host.browserRun;
-    }
-  }
-  return { ctx: out };
-}
-
 /**
  * 写类 tool 步的目标文件若命中声明产物且已存在 → pre-Read 解除内核守卫。
  *
@@ -196,14 +215,17 @@ async function preReadDeclaredArtifact(
   if (typeof args.file_path !== 'string') return;
 
   const norm = (p: string): string => {
-    const abs = resolve(ctx.cwd, 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 ?? [])];
+  const declared = [
+    ...(ctx.declaredArtifacts ?? []),
+    ...(step.artifacts ?? []),
+  ];
   if (!declared.some((a) => norm(a) === target)) return;
 
-  const abs = resolve(ctx.cwd, args.file_path);
+  const abs = resolve(effectiveWorkflowCwd(ctx), args.file_path);
   if (!existsSync(abs)) return; // 新建文件不需要解守卫
 
   // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
@@ -214,7 +236,7 @@ async function preReadDeclaredArtifact(
   //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
   //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
   // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
-  recordRead(abs, { truncated: false });
+  recordRead(abs, { truncated: false }, ctx.sessionState?.fileReads);
 }
 
 /**

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+export function effectiveWorkflowCwd(ctx) {
+    return ctx.sessionState?.activeWorktree?.path ?? ctx.cwd;
+}
+export function buildWorkflowToolContext(step, ctx, toolCallId, reportProgress) {
+    const context = {
+        ...ctx.toolContext,
+        history: ctx.history,
+        sessionState: ctx.sessionState,
+        provider: ctx.provider,
+        toolGate: ctx.host?.toolGate ?? ctx.toolContext?.toolGate,
+        promptCache: ctx.promptCache ?? ctx.toolContext?.promptCache,
+        workspaceId: ctx.runtimeContext?.workspaceId ?? ctx.toolContext?.workspaceId,
+        sessionId: ctx.runtimeContext?.sessionId ?? ctx.toolContext?.sessionId,
+        memoryAccess: ctx.runtimeContext?.memoryAccess ?? ctx.toolContext?.memoryAccess,
+        cwd: effectiveWorkflowCwd(ctx),
+        toolCallId,
+        reportProgress,
+    };
+    for (const capability of step.uses ?? []) {
+        if (capability === 'computer') {
+            if (!ctx.host?.computerRun) {
+                return {
+                    error: 'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— ' +
+                        '请在支持 Computer Use 的宿主启动，或去掉该步的 uses 声明。',
+                };
+            }
+            context.computerRun = ctx.host.computerRun;
+            if (ctx.host.computerIntervention) {
+                context.computerIntervention = ctx.host.computerIntervention;
+            }
+            continue;
+        }
+        if (capability === 'browser') {
+            if (!ctx.host?.browserRun) {
+                return {
+                    error: 'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。',
+                };
+            }
+            context.browserRun = ctx.host.browserRun;
+        }
+    }
+    return context;
+}

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

@@ -0,0 +1,64 @@
+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.
+ */
+export function effectiveWorkflowCwd(ctx: RunContext): string {
+  return ctx.sessionState?.activeWorktree?.path ?? ctx.cwd;
+}
+
+export function buildWorkflowToolContext(
+  step: StepDef,
+  ctx: RunContext,
+  toolCallId: string,
+  reportProgress: NonNullable<ToolCallContext['reportProgress']>,
+): ToolCallContext | { error: string } {
+  const context: ToolCallContext = {
+    ...ctx.toolContext,
+    history: ctx.history,
+    sessionState: ctx.sessionState,
+    provider: ctx.provider,
+    toolGate: ctx.host?.toolGate ?? ctx.toolContext?.toolGate,
+    promptCache: ctx.promptCache ?? ctx.toolContext?.promptCache,
+    workspaceId:
+      ctx.runtimeContext?.workspaceId ?? ctx.toolContext?.workspaceId,
+    sessionId: ctx.runtimeContext?.sessionId ?? ctx.toolContext?.sessionId,
+    memoryAccess:
+      ctx.runtimeContext?.memoryAccess ?? ctx.toolContext?.memoryAccess,
+    cwd: effectiveWorkflowCwd(ctx),
+    toolCallId,
+    reportProgress,
+  };
+
+  for (const capability of step.uses ?? []) {
+    if (capability === 'computer') {
+      if (!ctx.host?.computerRun) {
+        return {
+          error:
+            'uses:[computer] 声明了需要电脑操控能力，但本次运行的宿主没有提供 —— ' +
+            '请在支持 Computer Use 的宿主启动，或去掉该步的 uses 声明。',
+        };
+      }
+      context.computerRun = ctx.host.computerRun;
+      if (ctx.host.computerIntervention) {
+        context.computerIntervention = ctx.host.computerIntervention;
+      }
+      continue;
+    }
+
+    if (capability === 'browser') {
+      if (!ctx.host?.browserRun) {
+        return {
+          error:
+            'uses:[browser] 声明了需要浏览器授权上下文，但本次运行的宿主没有提供。',
+        };
+      }
+      context.browserRun = ctx.host.browserRun;
+    }
+  }
+
+  return context;
+}

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

@@ -16,9 +16,11 @@
 import type {
   ImageDetail,
   Message,
+  PluginContext,
   Provider,
   SessionState,
   Tool,
+  ToolCallContext,
 } from '../../../src/plugin-sdk.js';
 
 // ---------------- 1. Workflow / Step 定义 ----------------
@@ -237,7 +239,7 @@ export interface StepDef {
   /** ADR-05: 仅 llm 节点声明的上下文文件清单（skill 节点 loader 拒绝）；runner 拼 path+hint 进 prompt 并开放 Read 子循环，不 inline 内容。 */
   context_files?: Array<{ path: string; hint?: string }>;
 
-  /** ADR-05: agent 节点的工具白名单；未声明时默认全量 ALL_TOOLS。 */
+  /** ADR-05: agent 节点的工具白名单；未声明时继承宿主过滤后的有效工具集。 */
   allowed_tools?: string[];
 
   /**
@@ -437,10 +439,9 @@ export interface RunContext {
   cwd: string;
   /**
    * 可用工具列表。
-   * v0.9 重构后：agent/llm/skill 步委托 runQuery(TAOR) 执行，
-   * runQuery 内部使用自己的 ALL_TOOLS 全量工具列表。
-   * 此字段保留给 runner 内部确定性步（tool 步）的 executeTool 调度使用，
-   * 以及测试兼容。生产路径由 plugin.ts 注入 ALL_TOOLS。
+   * agent/llm/skill 与确定性 tool 步都以此列表为宿主授权上限。
+   * plugin.ts 先按 runtime 和父宿主白名单过滤，再把同一列表交给提示词、
+   * Schema 和真实执行，任何工作流节点都不能从 ALL_TOOLS 恢复隐藏能力。
    */
   tools: Tool[];
   transientContext?: string;
@@ -494,11 +495,29 @@ export interface RunContext {
     tools: import('../../../src/plugin-sdk.js').Tool[];
     signal?: AbortSignal;
     promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
-  }) => AsyncGenerator<import('../../../src/plugin-sdk.js').LlmStreamEvent, void, undefined>;
+  }) => AsyncGenerator<
+    import('../../../src/plugin-sdk.js').LlmStreamEvent,
+    void,
+    undefined
+  >;
   /**
    * DI：executeTool 实现（仅测试用）。同上。
    */
-  executeTool?: (name: string, rawArgsJson: string, signal?: AbortSignal) => Promise<import('../../../src/plugin-sdk.js').ToolResult>;
+  executeTool?: PluginContext['executeTool'];
+  /**
+   * Canonical non-model-visible context shared by deterministic tool nodes.
+   * Browser/computer capabilities are deliberately excluded here and are only
+   * added by the step-level `uses` slicer.
+   */
+  toolContext?: Omit<
+    ToolCallContext,
+    | 'browserRun'
+    | 'computerRun'
+    | 'computerIntervention'
+    | 'reportProgress'
+    | 'toolCallId'
+    | 'cwd'
+  >;
   /**
    * 会话状态（驱动 microCompact / reactiveCompact）。
    *