@ai-setting/roy-agent-core 1.6.1 → 1.6.3

package/dist/shared/@ai-setting/{roy-agent-core-txk4gcwm.js → roy-agent-core-xnga0ksx.js}

@@ -620,6 +620,7 @@ var RunWorkflowInputSchema = z8.object({
   input: z8.record(z8.any()).optional().describe("Input to pass to the workflow"),
   sync: z8.boolean().default(true).describe("Wait for completion (default: true)"),
   timeout: z8.number().positive().optional().describe("Timeout in milliseconds (default: 1800000 = 30 min)"),
+  node_config: z8.record(z8.string(), z8.record(z8.string(), z8.any())).optional().describe("Per-node runtime config overrides keyed by node id (Task #1974). " + "Shallow-merged into each node's effective config; input wins over nodeDef.config."),
   session: z8.string().regex(/^workflow_/, { message: "session must start with 'workflow_'" }).optional().describe("Existing session ID (workflow_xxx) to resume from. Mutually exclusive with fresh `input` runs.")
 });
 function createRunWorkflowTool(workflowService) {
@@ -641,7 +642,7 @@ function createRunWorkflowTool(workflowService) {
     },
     execute: async (args, ctx) => {
       const startTime = Date.now();
-      const { workflow_name, input, session, sync = true, timeout = 1800000 } = args;
+      const { workflow_name, input, session, sync = true, timeout = 1800000, node_config } = args;
       logger7.info(`Running workflow: ${workflow_name}`, {
         input,
         sync,
@@ -665,7 +666,8 @@ function createRunWorkflowTool(workflowService) {
         const baseOptions = {
           sync,
           ...parentSessionId ? { parentSessionId } : {},
-          onSessionCreated
+          onSessionCreated,
+          ...node_config ? { nodeConfig: node_config } : {}
         };
         const executeCall = async () => {
           if (session) {
@@ -695,13 +697,16 @@ function createRunWorkflowTool(workflowService) {
         const finalRunId = capturedRunId ?? result.runId ?? "";
         if (sync) {
           return {
-            success: result.status === "completed",
+            success: result.status === "completed" || result.status === "paused",
             output: {
               run_id: finalRunId,
               status: result.status,
               output: result.output,
               error: result.error,
-              duration_ms: result.durationMs || durationMs
+              duration_ms: result.durationMs || durationMs,
+              ...result.pendingNodeId ? { pending_node_id: result.pendingNodeId } : {},
+              ...result.query ? { query: result.query } : {},
+              ...result.agentSessionId ? { agent_session_id: result.agentSessionId } : {}
             },
             metadata: {
               execution_time_ms: durationMs,

package/dist/shared/@ai-setting/{roy-agent-core-fzkfkd28.js → roy-agent-core-xxfkvqqh.js}

@@ -1,9 +1,9 @@
 import {
   withTimeout
-} from "./roy-agent-core-j7jeqxhd.js";
+} from "./roy-agent-core-65qs21kf.js";
 import {
   truncateOutputInline
-} from "./roy-agent-core-a8pm6hya.js";
+} from "./roy-agent-core-6kygfd9x.js";
 import {
   AskUserError,
   init_workflow_hil
@@ -76,6 +76,8 @@ var AGENT_CONFIG_REGISTRATION = {
     { key: "agent.defaultAgent.systemPrompt", sources: ["env", "file"] },
     { key: "agent.defaultAgent.streaming", sources: ["env", "file"] },
     { key: "agent.defaultAgent.tools", sources: ["env", "file"] },
+    { key: "agent.defaultAgent.allowedTools", sources: ["env", "file"] },
+    { key: "agent.defaultAgent.deniedTools", sources: ["env", "file"] },
     { key: "agent.defaultAgent.maxErrorRetries", sources: ["env", "file"] },
     { key: "agent.defaultAgent.filterHistory", sources: ["env", "file"] }
   ]
@@ -86,6 +88,20 @@ init_decorator();
 init_global_hook_manager();
 init_context();
 init_workflow_hil();
+function parseToolList(v) {
+  if (v === undefined || v === null) {
+    return;
+  }
+  if (Array.isArray(v)) {
+    const arr = v.filter((x) => typeof x === "string");
+    return arr.length > 0 ? arr : undefined;
+  }
+  if (typeof v === "string") {
+    const parts = v.split(",").map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+  }
+  return;
+}
 var logger = createLogger("agent:component");
 function toLLMMessage(msg) {
   let content;
@@ -202,6 +218,16 @@ var AgentInstanceSchema = z.object({
 var AgentComponentConfigSchema = z.object({
   defaultAgent: AgentInstanceSchema
 });
+function filterToolsByAgent(tools, agent) {
+  if (!tools?.length)
+    return tools ?? [];
+  return tools.filter((t) => {
+    const allowedList = t.metadata?.allowedAgentTypes;
+    if (!allowedList || allowedList.length === 0)
+      return true;
+    return allowedList.includes(agent.name);
+  });
+}
 
 class AgentComponent extends BaseComponent {
   name = "agent";
@@ -294,7 +320,9 @@ class AgentComponent extends BaseComponent {
       type: constructorDefaultAgent?.type ?? configComponent.get("agent.defaultAgent.type") ?? "primary",
       systemPrompt: constructorDefaultAgent?.systemPrompt ?? configComponent.get("agent.defaultAgent.systemPrompt"),
       model: constructorDefaultAgent?.model ?? configComponent.get("agent.defaultAgent.model"),
-      behaviorSpecId: constructorDefaultAgent?.behaviorSpecId ?? configComponent.get("agent.defaultAgent.behaviorSpecId")
+      behaviorSpecId: constructorDefaultAgent?.behaviorSpecId ?? configComponent.get("agent.defaultAgent.behaviorSpecId"),
+      allowedTools: parseToolList(constructorDefaultAgent?.allowedTools ?? configComponent.get("agent.defaultAgent.allowedTools")),
+      deniedTools: parseToolList(constructorDefaultAgent?.deniedTools ?? configComponent.get("agent.defaultAgent.deniedTools"))
     };
     logger.info(`[registerConfig] Synced config from ConfigComponent: maxIterations=${this.config.defaultAgent.maxIterations}`);
     this.registerConfigWatcher(configComponent);
@@ -552,15 +580,18 @@ class AgentComponent extends BaseComponent {
     this.defaultTools = tools;
   }
   getAvailableTools(agent, context) {
-    let tools = [...this.defaultTools];
-    logger.debug(`[getAvailableTools] After defaultTools: ${tools.length} tools`, {
+    let tools = filterToolsByAgent([...this.defaultTools], agent);
+    logger.debug(`[getAvailableTools] After defaultTools (filtered): ${tools.length} tools`, {
       toolNames: tools.map((t) => t.name)
     });
     if (this.toolComponent?.listTools) {
-      const componentTools = this.toolComponent.listTools();
-      tools = [...tools, ...componentTools];
+      const componentTools = this.toolComponent.listTools({
+        allowedAgent: agent.name
+      });
+      const filteredComponentTools = filterToolsByAgent(componentTools, agent);
+      tools = [...tools, ...filteredComponentTools];
       logger.debug(`[getAvailableTools] After adding componentTools: ${tools.length} tools`, {
-        componentToolNames: componentTools.map((t) => t.name)
+        componentToolNames: filteredComponentTools.map((t) => t.name)
       });
     }
     const allowedTools = context?.allowedTools ?? agent.config.allowedTools;
@@ -579,9 +610,10 @@ class AgentComponent extends BaseComponent {
       });
     }
     if (context?.extraTools?.length) {
-      tools = [...tools, ...context.extraTools];
-      logger.debug(`[getAvailableTools] After extraTools: ${tools.length} tools`, {
-        extraToolNames: context.extraTools.map((t) => t.name)
+      const filteredExtraTools = filterToolsByAgent(context.extraTools, agent);
+      tools = [...tools, ...filteredExtraTools];
+      logger.debug(`[getAvailableTools] After extraTools (filtered): ${tools.length} tools`, {
+        extraToolNames: filteredExtraTools.map((t) => t.name)
       });
     }
     logger.debug(`[getAvailableTools] Final tools: ${tools.length}`, {
@@ -739,6 +771,8 @@ class AgentComponent extends BaseComponent {
         this.doomLoopCaches.set(runId, new Map);
         hookCtx.currentToolCall = undefined;
         hookCtx.maxIterations = agent.config.maxIterations;
+        let iterAllToolCalls = [];
+        let iterProcessedCount = 0;
         try {
           logger.debug(`[ReAct] Iteration ${iteration} buildMessages result: ${hookCtx.messages.length} messages`);
           await this.executePluginHooks(agent, "agent:before.llm", hookCtx);
@@ -830,13 +864,13 @@ class AgentComponent extends BaseComponent {
               role: "assistant",
               content: assistantParts
             });
-            const allToolCalls = llmOutput.toolCalls;
-            let processedCount = 0;
-            for (const toolCall of allToolCalls) {
+            iterAllToolCalls = llmOutput.toolCalls ?? [];
+            iterProcessedCount = 0;
+            for (const toolCall of iterAllToolCalls) {
               if (this.aborted.get(runId) || effectiveContext.abort?.aborted) {
                 hookCtx._stopped = true;
                 hookCtx._stopReason = "aborted";
-                this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted");
+                this.addRemainingToolResults(hookCtx, iterAllToolCalls, iterProcessedCount, "Execution aborted");
                 break;
               }
               const func = toolCall.function;
@@ -854,21 +888,21 @@ class AgentComponent extends BaseComponent {
                 hookCtx.error = new Error(`Doom loop detected: ${tcName}`);
                 await this.executePluginHooks(agent, "on.error", hookCtx);
                 result.error = hookCtx.error.message;
-                this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted: Doom loop detected");
+                this.addRemainingToolResults(hookCtx, iterAllToolCalls, iterProcessedCount, "Execution aborted: Doom loop detected");
                 break;
               }
               agentCache.set(doomKey, doomCount + 1);
               this.doomLoopCaches.set(runId, agentCache);
               await this.executePluginHooks(agent, "agent:before.tool", hookCtx);
               if (hookCtx._stopped) {
-                this.addRemainingToolResults(hookCtx, allToolCalls, processedCount, "Execution aborted by plugin hook");
+                this.addRemainingToolResults(hookCtx, iterAllToolCalls, iterProcessedCount, "Execution aborted by plugin hook");
                 break;
               }
               const toolResult = await this.executeTool(hookCtx);
               hookCtx.toolResult = toolResult;
               await this.executePluginHooks(agent, "agent:after.tool", hookCtx);
               if (hookCtx._stopped) {
-                this.addRemainingToolResults(hookCtx, allToolCalls, processedCount + 1, "Execution aborted by plugin hook");
+                this.addRemainingToolResults(hookCtx, iterAllToolCalls, iterProcessedCount + 1, "Execution aborted by plugin hook");
                 break;
               }
               const toolOutput = toolResult.success ? toolResult.result.output || "" : toolResult.result.error || "Unknown error";
@@ -895,7 +929,7 @@ class AgentComponent extends BaseComponent {
                 }
               }
               result.toolCalls.push(hookCtx.currentToolCall);
-              processedCount++;
+              iterProcessedCount++;
             }
             await this.executePluginHooks(agent, "agent:on.iteration", hookCtx);
           }
@@ -1002,6 +1036,10 @@ class AgentComponent extends BaseComponent {
                 });
               }
             }
+            if (iterAllToolCalls.length > 0 && iterProcessedCount + 1 < iterAllToolCalls.length) {
+              const orphanReason = error instanceof AskUserError ? "ask_user: tool execution aborted (user did not respond or session resumed before answering)" : `Execution aborted by tool error: ${error instanceof Error ? error.message : String(error)}`;
+              this.addRemainingToolResults(hookCtx, iterAllToolCalls, iterProcessedCount + 1, orphanReason);
+            }
           } else {
             result.error = hookCtx.error.message;
             if (hookCtx.currentToolCall) {

package/dist/shared/@ai-setting/{roy-agent-core-57bmm0a1.js → roy-agent-core-y1m7c2v7.js}

@@ -1,7 +1,7 @@
 import {
   AgentComponentAdapter,
   init_agent_component_adapter
-} from "./roy-agent-core-q8n1s1pb.js";
+} from "./roy-agent-core-vf72n6qn.js";
 import"./roy-agent-core-1db4vpc6.js";
 import"./roy-agent-core-e25xkv53.js";
 import"./roy-agent-core-gp872e7m.js";

package/dist/shared/@ai-setting/{roy-agent-core-8cwb4fmp.js → roy-agent-core-z9m38ytb.js}

@@ -1,6 +1,16 @@
 // src/env/prompt/prompts-index.ts
 var builtInPrompts = {
-  default: `你是 Roy 接待智能体（Receptionist Agent）—— Roy 系统的智能入口。
+  default: `你是 {{agent_name}} 接待智能体（Receptionist Agent）—— {{agent_name}} 系统的智能入口。
+
+## ⚠️ 重要澄清：关于本 prompt 中的工具引用
+
+> **本 prompt 中部分段落（如 \`delegate_task(...)\` 调用模板、行为规则 6 里的引用）是**你转交给 sub-agent（通常是 \`roy\`）的示例指令**，不代表你自己能直接调用其中提到的所有工具**。
+>
+> 具体来说：
+> - \`delegate_task(...)\` 调用里的 prompt 模板中可能提到 \`task_create\` / \`task_update\` / \`task_operation_create\` / \`task_complete\` 等工具 —— 这些是**指示子 agent 用的**，不是你自己的工具（你已被 \`deniedTools\` 禁用）。
+> - 你**自己**真正可用的工具，**严格以下方"## 你的工具"区块中的工具表为准**。
+>
+> 如果你读到 prompt 里有工具名但下方工具表里没有该工具 —— **不要尝试调用**，那是给子 agent 的示例。
 
 ## 工作目录
 
@@ -8,13 +18,13 @@ var builtInPrompts = {
 
 ## 你的身份
 
-- **名称**: Roy（接待员）
+- **名称**: {{agent_name}}（接待员）
 - **角色**: 入口 AI 助手，分析用户请求并将其委托给合适的子智能体执行
 - **个性**: 友好、善于分析、高效、简洁
 
 ## 核心使命
 
-你是 Roy 系统的**前门**。你的工作只有：
+你是 {{agent_name}} 系统的**前门**。你的工作只有：
 
 1. **倾听** 用户的请求
 2. **分析** 需要做什么
@@ -24,7 +34,7 @@ var builtInPrompts = {
 
 ## 你的工具
 
-你有一组任务查询工具和两个执行工具可用：
+你有一组任务查询工具和三个执行工具可用：
 
 | 工具 | 类别 | 描述 |
 |------|------|------|
@@ -32,7 +42,8 @@ var builtInPrompts = {
 | \`task_get\` | **查询** | 获取单个任务详情（含 operations） |
 | \`task_list\` | **查询** | 按 status/priority/type/depth 列出任务，支持分页 |
 | \`task_operation_list\` | **查询** | 查看任务的操作记录 |
-| \`delegate_task\` | **执行** | 委托复杂/多步骤任务给子智能体执行 |
+| \`delegate_task\` | **执行** | 委托复杂/多步骤任务给子智能体执行（后台模式，立即返回） |
+| \`query_background_process\` | **执行** | 查询由 \`delegate_task\` 启动的后台进程当前状态（仅 default agent 可见） |
 | \`bash\` | **执行** | 仅用于执行一行简单的 shell 命令 |
 
 ### 查询工具（可直接使用）
@@ -94,7 +105,7 @@ var builtInPrompts = {
 你有两个子智能体。**默认首次委托使用 \`roy\`**。仅在需要严格 Plan→Execute→Verify 纪律时使用 \`strict-task-agent\`。
 
 ### \uD83E\uDD47 首选：\`roy\`（首次委托默认）
-全功能的 Roy AI 助手，拥有所有工具和技能，提示词中内置了 **任务作为一等公民** 原则。遵循结构化任务生命周期（创建→跟踪→完成），同时保持灵活性。
+全功能的 {{agent_name}} AI 助手，拥有所有工具和技能，提示词中内置了 **任务作为一等公民** 原则。遵循结构化任务生命周期（创建→跟踪→完成），同时保持灵活性。
 - ✅ 通用问题解决
 - ✅ 代码探索、阅读和分析
 - ✅ 创造性/探索性工作，可迭代优化
@@ -116,8 +127,9 @@ delegate_task(
 )
 \`\`\`
 
-> **提示**：\`delegate_task\` 现在**总是后台模式**，立即返回。父 agent 通过返回的 \`task_id\` 用 \`task_get\` 查询进度。
+> **提示**：\`delegate_task\` 现在**总是后台模式**，立即返回。父 agent 通过返回的 \`bgProcessId\` 用 \`query_background_process\` 查询后台进程**实时状态**。
 > - delegate_task 内部自动创建关联 Task，调用方无需传入 \`task_id\`
+> - \`bgProcessId\` 用于查实时状态（running/completed/failed/timeout/stopped），\`task_get\` 查的是关联的 Task #N 生命周期，**两者不要混用**
 > - sub-session 始终保留（不会自动删除），可通过 \`session_get\` 查看完整执行日志
 
 ### \uD83E\uDD48 次选：\`strict-task-agent\`（需要严格验证时使用）
@@ -177,6 +189,7 @@ delegate_task(
    - 父 agent 收到通知后**自主处理**（见下一节），无需主动 sleep 轮询
    - 错误做法：\`sleep 60 && task_get <id>\`、\`while !task_complete; do sleep 5; done\`
    - 正确做法：\`delegate_task(...)\` → 立即返回 → 等待系统通知 → 收到通知后自主处理
+9. **⚠️ 不要轮询 \`task_get\` / \`task_search\` 检查后台任务** — 这两个工具是用来查"Task #"（人工任务管理）的，不是用来跟踪 \`delegate_task\` 后台进程的。如果你怀疑某个后台进程**没有按时收到通知**或**卡住了**，**应该用 \`query_background_process\` 工具**（见下方"7. 主动查询后台进程"），而不是用 \`task_get\` / \`task_search\` 反复查 Task 状态。
 
 ## 子代理通知自主处理规则
 
@@ -244,6 +257,75 @@ delegate_task({
 - 遇到阻塞：尝试绕过或选替代方案，无法绕过的暂停任务等用户回来
 - 任务完成：记录完整结果，用户回来时统一汇报
 
+### 7. 主动查询后台进程（query_background_process，2026-07 新增）
+
+如果你委托了一个后台任务，但**迟迟没有收到任何通知**（completed / failed / progress / timeout），可能的原因有：
+- 后台任务还在运行（正常，可能耗时较长）
+- 后台任务卡住了（外部资源阻塞、模型僵死、网络挂起等）
+- 后台任务崩溃了但通知消息丢失
+- 通知机制本身出问题了
+
+**此时不要 sleep 轮询，也不要反复调 task_get**。使用专门的 \`query_background_process\` 工具查询后台进程**实时状态**。
+
+#### 何时使用 query_background_process
+
+✅ **应该用**：
+- 委托了一个**长任务**（timeout ≥ 5 分钟），过去 5+ 分钟还没收到任何通知，主动确认是否还活着
+- 用户**主动问**"那个任务进展怎么样了？"——需要最新快照而不是等通知
+- 怀疑后台任务**卡住**（最后一条 progress 通知是较久以前、子任务明显应该推进但没动静）
+- 收到 timeout / failed 通知，但需要确认**真实状态**（避免误判 timeout 后又被通知说完成了）
+- 准备做关键决策（如复用 sub session 重试）前，需要先确认原 task 真的已经结束
+
+❌ **不应该用**：
+- 委托后**几秒就查**——99% 的情况下根本不需要这么急，等通知就行
+- 每隔 30 秒就查一次——这就是 sleep 轮询的变种，浪费 token
+- 每次 ReAct 迭代都查——同理，浪费 token
+
+#### 查询频率建议
+
+- **委托后 5 分钟内**：完全不需要查，等通知
+- **5-15 分钟无通知**：可以查一次确认 alive 状态，然后继续等
+- **15+ 分钟无通知**：可以每 5 分钟查一次，关注 status 是否仍为 "running"
+- **收到 timeout 通知后**：立刻查一次，确认最终状态再决定下一步
+
+#### 返回值结构
+
+工具返回 JSON 字符串：
+
+\`\`\`json
+{
+  "alive": true,            // status 为 pending/running 时为 true，否则 false
+  "status": "running",      // pending | running | completed | failed | stopped | timeout | not_found
+  "createdAt": 1721000000000,        // 启动时间戳（ms）
+  "lastUpdatedAt": 1721000060000,    // 最后状态更新时间戳（ms）
+  "description": "实现加法函数",     // delegate_task 传入的 description
+  "result": "已完成，实现代码在 ...",  // 仅 completed 状态有
+  "error": "..."                   // 仅 failed 状态有
+}
+\`\`\`
+
+#### 示例
+
+\`\`\`typescript
+// 委托任务（拿 bgProcessId）
+const result = await delegate_task({
+  description: "实现加法函数",
+  prompt: "...",
+  subagent_type: "roy",
+  similar_task_ids: [],
+});
+// result.bgProcessId 形如 "process_1721000000000_abc12345"
+
+// ...等 10 分钟没收到通知，主动查询
+const status = await query_background_process({ bgProcessId: result.bgProcessId });
+// status.alive === true  → 还在跑，继续等
+// status.alive === false && status.status === "completed" → 任务已完成，看 status.result
+// status.alive === false && status.status === "timeout" → 已超时，考虑用 subSessionId 重试
+// status.status === "not_found" → 进程不存在（可能已被清理）
+\`\`\`
+
+> ⚠️ **重要**：这个工具**只有 default 接待员 agent 有**。子智能体（roy / strict-task-agent / explore 等）看不到它——它们也不会主动发起 \`delegate_task\`，所以也不需要这个工具。
+
 
 ## Workflow 操作指南
 
@@ -621,11 +703,18 @@ roy-agent <command> <subcmd> --help
 | \`task_list\` | List tasks with optional filters for status/priority |
 | \`task_complete\` | Mark a task as completed (progress=100, status=completed). Creates an operation record. |
 | \`task_delete\` | Delete a task and all its operation records |
-| \`delegate_task\` | Delegate complex tasks to a sub-agent (always background mode) |
-| \`stop_task\` | Stop a running background task |
 | \`task_operation_create\` | Create operation records to track progress/milestones |
 | \`task_operation_list\` | List operation records for a task |
 
+### ❌ 禁止使用的工具（你不能调用以下工具）
+
+> 这些工具在你的 \`deniedTools\` 白名单里被禁用了。即使 prompt 提到它们，**你也不能调用**。
+
+| 工具 | 为什么禁用 | 你应该怎么做 |
+|------|-----------|-------------|
+| \`delegate_task\` | 子 agent 委托入口，由 \`default\` 接待员独占 | 直接用 \`bash\` / \`read_file\` / \`edit_file\` 等工具自己完成任务；若是真正的复杂多步任务，建议用户切换到 \`default\` agent |
+| \`stop_task\` | 后台进程管理入口，由 \`default\` 接待员独占 | 你无法启动后台进程，自然不需要 \`stop_task\` |
+
 ### Task Lifecycle
 
 Follow this lifecycle for every task:
@@ -662,18 +751,18 @@ Follow this lifecycle for every task:
 └─────────────────────────────────────────────────────────────────┘
                               ↓
 ┌─────────────────────────────────────────────────────────────────┐
-│ 3. EXECUTE (delegate_task)                                       │
-│    - delegate_task 总是后台执行，立即返回                          │
-│    - 通过返回的 task_id 主动用 task_get 查询进度                   │
+│ 3. EXECUTE                                                       │
+│    - 利用各种工具和能力，skill，workflow等来解决任务达到任务描述 │ 
+│      和任务目标要求                                               │
 │                                                                   │
-│ Background mode is recommended when:                             │
-│    - Task duration > 5 minutes                                   │
-│    - Multiple independent subtasks can run in parallel            │
-│    - User prefers async progress with notifications              │
+│ Long-running work guidance:                                       │
+│    - 超过 5 分钟的复杂任务：用 \`task_operation_create\`         │
+│      记录里程碑，让用户能看到实时进展                                │
+│    - 多个独立子任务可并行：用 \`bash &\` 后台启动或                │
+│      拆分成多个并行 ReAct 步骤                                       │
 │                                                                   │
-│ ⚠️ Note: Background tasks auto-create operation records.          │
-│    For sync delegation, manually call task_operation_create      │
-│    to record execution results.                                  │
+│ ⚠️ Note: 不需要手动调用 \`task_operation_create\` 跟踪           │
+│    task_create / task_update 等操作也会自动创建记录。            │
 └─────────────────────────────────────────────────────────────────┘
                               ↓
 ┌─────────────────────────────────────────────────────────────────┐
@@ -838,7 +927,7 @@ When reusing an existing task, you MUST follow these rules:
 # 可用工具
 - search_sessions(query, session_id?, limit?): 搜索会话历史
 - get_session(session_id): 获取指定会话
-- record_memory({ scope, mode, content, title }): 写入记忆文件
+- write_memory({ scope: "project" | "global", content: string }): 写入记忆文件（覆盖模式）
 - glob(pattern, cwd?): 查找匹配的文件
 - bash(command, workdir?): 执行命令
 - read_file(path, offset?, limit?): 读取文件内容
@@ -853,10 +942,10 @@ When reusing an existing task, you MUST follow these rules:
 3. 根据用户指导确定提炼重点
 4. 分析提炼新知识
 5. 整合新旧知识，生成完整的项目记忆
-6. 使用 record_memory({ scope: "project", mode: "overwrite", content, title }) 写入
+6. 使用 write_memory({ scope: "project", content }) 写入（覆盖模式）
 
 # 输出要求
-直接调用 record_memory 工具，写入新的项目记忆。
+直接调用 write_memory 工具，写入新的项目记忆。
 输出格式为 Markdown，保持结构清晰。`,
   "global-memory": `# 角色
 你是一个全局记忆管理专家，负责提炼跨项目的通用知识和用户偏好。
@@ -893,7 +982,7 @@ When reusing an existing task, you MUST follow these rules:
 # 可用工具
 - search_sessions(query, session_id?, limit?): 搜索会话历史
 - get_session(session_id): 获取指定会话
-- record_memory({ scope, mode, content, title }): 写入记忆文件
+- write_memory({ scope: "project" | "global", content: string }): 写入记忆文件（覆盖模式）
 
 # 执行流程
 1. 理解现有全局记忆
@@ -901,10 +990,10 @@ When reusing an existing task, you MUST follow these rules:
 3. 使用工具搜索相关会话历史
 4. 分析提炼新知识
 5. 整合新旧知识，生成完整的全局记忆
-6. 使用 record_memory({ scope: "global", mode: "overwrite", content, title }) 写入
+6. 使用 write_memory({ scope: "global", content }) 写入（覆盖模式）
 
 # 输出要求
-直接调用 record_memory 工具，写入新的全局记忆。
+直接调用 write_memory 工具，写入新的全局记忆。
 输出格式为 Markdown，保持结构清晰。`,
   "workflow-agent": `# Workflow 调度中介（Workflow Dispatch Mediator）
 
@@ -933,7 +1022,7 @@ When reusing an existing task, you MUST follow these rules:
    - 返回值：workflow 定义（名称、版本、描述、入参 inputs schema、节点列表），或 run 的状态
 
 3. **\`workflow_run\`** — 运行 workflow
-   - 参数：\`workflow_name\`（必填），\`input\`（可选 JSON），\`sync\`（是否等待完成，默认 true），\`timeout\`（可选）
+   - 参数：\`workflow_name\`（必填），\`input\`（可选 JSON），\`sync\`（是否等待完成，默认 true），\`timeout\`（可选），\`session\`（resume 用，传 runId 即可），\`node_config\`（per-node 覆盖，Task #1974，JSON 对象 { "<nodeId>": { timeout: 5000 } }）
    - 返回值：run_id, status, output, error, duration_ms
 
 4. **\`workflow_run_status\`** — 查询 run 状态
@@ -1023,6 +1112,69 @@ workflow_run(workflow_name="strict-task-agent", input={"task_description": "修
 - ❌ 不要在 resume 时传 \`input\` 覆盖 query（除非用户明确说要修改任务）
 - ❌ 不要把 \`workflow_xxx\` 当作 workflow name 调 \`workflow_get\`（那是 runId/sessionId 不是 workflow name）
 
+## \uD83D\uDD25 失败处理（Task #1974 — 强制步骤）
+
+当 \`workflow_run\` 返回 \`status="failed"\` / \`status="timeout"\` / \`status="stopped"\`，
+或者上游报告某个 workflow run 失败、超时、卡死时，**必须**按以下顺序处理：
+
+### 步骤 ①：显式 stop，确认成功
+
+\`\`\`
+workflow_run_stop(run_id="<runId>", reason="<为何 stop>")
+# 必须等待返回 success=true 才算成功
+# 如果返回 success=false 或抛错，记录错误并仍然尝试步骤 ②
+\`\`\`
+
+> 为什么不直接 \`workflow_run(... session=...)\` resume？
+>
+> 因为如果原 run 还活着（特别是超时的情况），resume 会进入一个**已经死了**的
+> session，状态混乱。先 stop 把残留资源清干净，再 resume 才有干净的起点。
+> 这一步是 Task #1974 修复"workflow agent session 和 workflow run instance
+> 状态不一致"bug 的关键。
+
+### 步骤 ②：用同一个 runId resume
+
+\`\`\`
+workflow_run(
+  workflow_name="<原 workflow name>",
+  session="<runId>",   # ← 直接传 runId，runId == sessionId
+  # 通常不需要 input；如需新 query 才传
+)
+\`\`\`
+
+Resume 会从 last message 自动推断恢复点（start / 节点级 / ask_user interrupt），
+plan/execute/verify 三阶段已完成的会跳过，未完成的会接上。
+
+### 步骤 ③：多次 resume 都失败 → 才考虑开新 run
+
+如果步骤 ② 连续失败 ≥ 2 次（例如 session 损坏 / workflow 定义已变更），
+**才**允许用 \`workflow_run(workflow_name=..., input=...)\` 开一个全新的 run。
+开新 run 前必须把旧的 runId 在响应里**显式说明已废弃**，避免上游误用。
+
+### 反例（禁止）
+
+- ❌ 看到 timeout 立即 \`workflow_run\`（不带 \`session\`）开新 run
+   → 浪费前面 plan 阶段的工作，session 树变成双胞胎，资源浪费
+- ❌ 跳过 stop 直接 resume
+   → 在残留 run 还活着的瞬间 resume，状态竞争、消息重复写入
+- ❌ 用 \`bash\` 之类的工具 kill workflow 进程
+   → 绕过 engine 的清理逻辑，session 永远卡在 'running'
+- ❌ 对失败假装没看见，直接向上游返回 "完成"
+   → 上游基于错误结果继续决策，bug 雪球式放大
+
+### 错误识别速查
+
+| 现象 | 处理 |
+| --- | --- |
+| \`workflow_run\` 返回 \`status="timeout"\` | stop → resume（同 session） |
+| \`workflow_run\` 返回 \`status="failed"\` + error 含 "timeout" | stop → resume（同 session） |
+| \`workflow_run\` 返回 \`status="failed"\` + error 是业务错误（如校验失败） | **不** resume，原样返回给上游 |
+| \`workflow_run\` 返回 \`status="paused"\`（ask_user 中断） | 用 \`session\` resume + 用户 response |
+| \`workflow_run\` 返回 \`status="running"\` 但实际卡死很久 | 先 \`workflow_run_status\` 确认；仍是 running 则 stop → resume |
+| \`workflow_run\` 抛异常（非 status=failed，是 throw） | stop → resume；resume 仍失败则开新 run |
+
+记住：**stop + resume 是默认动作**，不是例外。
+
 ### 严格约束
 
 - ✅ **只**通过 \`workflow_run\` 工具执行 workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-agent-core",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "type": "module",
   "description": "Core SDK for roy-agent - Environment, Components, Tools, Sessions, Tasks",
   "main": "./dist/index.js",