@yeaft/webchat-agent 1.0.453 → 1.0.456

package/yeaft/tools/send-message.js

@@ -19,12 +19,13 @@ export default defineTool({
 Use this to give the sub-agent more work, additional instructions, or relay
 information. The prompt is queued for the agent to process on its next turn.
 
-IMPORTANT — PromptAgent only QUEUES the message; it does NOT block. After this
-returns you almost always want to call WaitAgent next to collect the reply.
-Do NOT end your turn after PromptAgent without either (a) calling WaitAgent,
-(b) explaining to the user what you just asked the sub-agent, or (c) calling
-CloseAgent. The orchestration loop is
-SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
+IMPORTANT — PromptAgent only QUEUES the message; it does NOT block. A follow-up
+is unfinished until you collect the reply. After PromptAgent returns, call
+WaitAgent in the same parent turn. If WaitAgent reports running/timedOut, call
+WaitAgent again with a larger bounded timeout unless the agent is stale/stalled.
+When the reply arrives, relay the result to the user or
+continue the work that depends on it. Do not end the parent turn immediately
+after PromptAgent.
 
 PromptAgent is rejected if the sub-agent is in a terminal state
 (completed/failed/closed/abandoned). Use SpawnAgent to start a fresh one.`,
@@ -32,10 +33,10 @@ PromptAgent is rejected if the sub-agent is in a terminal state
 
 用于给子 Agent 更多工作、额外指令或传递信息。提示会排队等待子 Agent 在其下一个 turn 处理。
 
-重要——PromptAgent 仅将消息排队，不阻塞。返回后你通常需要立即调用 WaitAgent 来收集回复。
-不要在 PromptAgent 后直接结束 turn，除非：(a) 调用 WaitAgent，(b) 向用户说明你刚让子 Agent
-做了什么，或 (c) 调用 CloseAgent。编排循环为：
-SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用户。
+重要——PromptAgent 仅将消息排队，不阻塞。后续任务只有拿到回复才算完成。PromptAgent 返回后，
+父级必须在同一个 turn 调用 WaitAgent。如果 WaitAgent 返回 running/timedOut，除非 Agent 已经
+stale/stalled，否则必须使用更大的有界 timeout 再次调用 WaitAgent。回复到达后，必须向用户转述结果或继续执行
+依赖该结果的工作。禁止在 PromptAgent 后立刻结束父级 turn。
 
 如果子 Agent 处于终止状态（completed/failed/closed/abandoned），PromptAgent 会被拒绝。
 用 SpawnAgent 启动新的。`
@@ -125,6 +126,11 @@ SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用
       content: message,
       timestamp: Date.now(),
     });
+    // WaitAgent uses this marker to distinguish an explicitly queued follow-up
+    // from an ordinary asynchronous SpawnAgent run. A bounded timeout must not
+    // silently downgrade the same-parent-turn collection contract.
+    agent.promptReplyPending = true;
+    agent.promptReplyPendingAt = Date.now();
     if (agent.status === STATUS.IDLE || agent.status === STATUS.CREATED) {
       agent.status = STATUS.RUNNING;
     }
@@ -132,15 +138,15 @@ SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用
     return JSON.stringify({
       next_steps:
         'Message is queued — the sub-agent has NOT replied yet. Call WaitAgent ' +
-        'next to collect the reply, then relay it to the user. Do NOT end your ' +
-        'turn here without either waiting for the reply or telling the user ' +
-        'what you just asked.',
+        'in this parent turn and collect the reply. If it is still running, call ' +
+        'WaitAgent again with a larger bounded timeout unless it is stale/stalled. ' +
+        'Relay the reply or continue the dependent work; do NOT end now.',
       success: true,
       agentId: agent_id,
       name: agent.name,
       messageCount: agent.messages.length,
       pending: agent.pendingPrompts.length,
-      message: `Message sent to agent "${agent.name}". Use WaitAgent to collect its reply.`,
+      message: `Message sent to agent "${agent.name}". Call WaitAgent now; the reply is still pending.`,
     });
   },
 });

package/yeaft/tools/skill.js

@@ -86,6 +86,7 @@ Actions:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  duplicateCallPolicy: () => 'suppress',
   async execute(input, ctx) {
     const skillManager = ctx?.skillManager;
 

package/yeaft/tools/start-plan.js

@@ -46,7 +46,7 @@ export default defineTool({
 This tool returns a planning instruction. Use it to land a structured plan, then keep working in the same turn. The expected flow is:
 1. Produce a short prose plan (problem, approach, risks).
 2. Call \`TodoWrite\` with the ordered steps. Mark the first concrete step "in_progress", the rest "pending".
-3. When the first-step tools and arguments are already known, emit \`TodoWrite\` and those independent tool calls in the same assistant response. Wait only when a result genuinely determines the next action.
+3. Emit \`TodoWrite\` with a first work-tool call only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call; inspect its result before issuing calls it could change or make unnecessary.
 
 WHEN TO USE:
 - Multi-step implementation (3+ steps), refactor, or open-ended investigation.
@@ -65,7 +65,7 @@ The tool takes the topic plus optional guiding fields (stuckAt, userProblem, exp
 此工具返回规划指令。用它产出一份结构化计划，然后在同一个 turn 中继续工作。预期流程是：
 1. 产出简短文字计划（问题、方法、风险）。
 2. 调用 TodoWrite 写出有序步骤。将第一个具体步骤标记为 "in_progress"，其余标记为 "pending"。
-3. 如果第一步所需的工具和参数已经确定，应在同一个 assistant response 中发出 TodoWrite 和这些彼此独立的工具调用；只有某个结果确实决定下一动作时才等待。
+3. 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 TodoWrite 一起发出。先执行满足条件的最小调用；如果结果可能改变或使后续调用不再必要，应先检查结果。
 
 何时使用：
 - 多步骤实现（3+ 步）、重构或开放式调查。
@@ -173,8 +173,8 @@ The tool takes the topic plus optional guiding fields (stuckAt, userProblem, exp
     }
     lines.push('');
     const nextInstruction = String(language).toLowerCase().startsWith('zh')
-      ? '下一步：产出计划并调用 `TodoWrite`。如果第一步的工具和参数已经确定，在同一个 assistant response 中一并发出这些彼此独立的工具调用。只有第一步必须询问用户时才在计划后停下。'
-      : 'Next: produce the plan and call `TodoWrite`. If the first-step tools and arguments are already known, emit those independent tool calls in the same assistant response. Stop after the plan only when the first step must ask the user.';
+      ? '下一步：产出计划并调用 `TodoWrite`。只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中发出这个最小调用；如果结果可能改变后续调用，先检查结果。只有第一步必须询问用户时才在计划后停下。'
+      : 'Next: produce the plan and call `TodoWrite`. Emit only the smallest first work-tool call whose necessity, arguments, and safety do not depend on another result; inspect its result before calls it could change. Stop after the plan only when the first step must ask the user.';
     lines.push(nextInstruction);
 
     return lines.join('\n');

package/yeaft/tools/todo-write.js

@@ -36,7 +36,7 @@ WHEN TO USE:
 FIRST CALL — PLAN WITHOUT AN EXTRA MODEL ROUND:
 - Write a short visible prose plan in the same assistant response: problem, approach, and risks.
 - Call TodoWrite directly; do not call a separate planning-mode tool first.
-- If the first work tools and arguments are known, emit them beside TodoWrite in that same response.
+- Emit TodoWrite beside the first work-tool call only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call.
 
 HOW TO USE:
 - First call: enumerate all the todos with status "pending", set exactly one to "in_progress".
@@ -45,8 +45,8 @@ HOW TO USE:
 - \`content\` is the imperative form ("Run tests"); \`activeForm\` is the present-continuous shown during execution ("Running tests").
 
 BATCH WITH WORK:
-- Avoid an intermediate TodoWrite-only model round when the next work tool and its arguments are already known. Emit TodoWrite and those independent work tool calls in the same assistant response.
-- This is batching, not speculative progress: mark work completed only after evidence. Keep calls separate when a pending result can change the next action, its arguments, or its safety.
+- Avoid an intermediate TodoWrite-only model round only when the next work-tool call passes the necessity, argument-independence, and safety-independence test. Emit that minimal call beside TodoWrite.
+- Do not speculative-batch an investigation. Mark work completed only after evidence, and inspect a pending result before issuing any call it could change, invalidate, or make unnecessary.
 - A standalone TodoWrite remains valid when no work tool should follow, including final completion or a blocking user question.
 
 WHEN NOT TO USE:
@@ -61,7 +61,7 @@ WHEN NOT TO USE:
 首次调用——不要浪费额外模型回合进入规划模式：
 - 在同一个 assistant response 中先写简短可见计划：问题、方案和风险。
 - 直接调用 TodoWrite，不要先调用单独的规划模式工具。
-- 如果第一批工作工具及参数已经确定，把它们和 TodoWrite 在同一响应中发出。
+- 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才把它与 TodoWrite 在同一响应中发出；先执行满足条件的最小调用。
 
 如何使用：
 - 首次调用：枚举所有 todo，状态为 "pending"，将其中恰好一个设为 "in_progress"。
@@ -70,8 +70,8 @@ WHEN NOT TO USE:
 - content 是祈使形式（如 "Run tests"）；activeForm 是执行时显示的进行时态（如 "Running tests"）。
 
 和工作工具合批：
-- 如果下一项工作所用的工具和参数已经确定，不要让中间状态的 TodoWrite 单独占一个模型回合；应在同一个 assistant response 中发出 TodoWrite 和这些彼此独立的工作工具调用。
-- 这是合批，不是提前宣告进度：只有已有证据时才能把工作标记为完成。如果待返回结果可能改变下一动作、参数或安全性，就必须分开调用。
+- 只有下一个工作工具调用通过必要性、参数独立性和安全独立性检查时，才避免让中间状态的 TodoWrite 单独占一个模型回合；把这个最小调用与 TodoWrite 一起发出。
+- 不要推测性批量展开调查。只有已有证据时才能把工作标记为完成；如果待返回结果可能改变、否定或使后续调用不再必要，应先检查该结果。
 - 没有工作工具应继续执行时（包括记录最终完成态或询问阻塞问题），TodoWrite 仍可单独调用。
 
 何时不使用：

package/yeaft/tools/types.js

@@ -72,6 +72,10 @@
  * @property {boolean | ((input?: object) => boolean)} [cacheWithinQuery] — explicitly safe to reuse for identical calls in one query
  * @property {boolean | ((input?: object) => boolean)} [mayMutateWorkspaceAfterReturn] — may keep changing the workspace after execute() resolves; disables same-query read reuse
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
+ * @property {(input?: object) => 'allow' | 'warn' | 'suppress'} [duplicateCallPolicy]
+ *   — repeated exact-call policy for one query. Use `allow` for polling/time-varying
+ *   tools and `suppress` only when the result is stable for the whole query.
+ *   Errors are never counted as successful duplicates.
  * @property {'json-error-envelope' | null} [errorOutput] — explicit returned-output error contract; null means only thrown errors fail
  * @property {string} [mcpServer] — owning MCP server for flattened MCP tools
  * @property {'external' | 'run'} [sideEffectScope] — whether mutations escape the current Run collector
@@ -90,6 +94,7 @@
  *   cacheWithinQuery?: boolean | ((input?: object) => boolean),
  *   mayMutateWorkspaceAfterReturn?: boolean | ((input?: object) => boolean),
  *   isDestructive?: (input?: object) => boolean,
+ *   duplicateCallPolicy?: (input?: object) => 'allow' | 'warn' | 'suppress',
  *   errorOutput?: 'json-error-envelope' | null,
  *   mcpServer?: string,
  *   sideEffectScope?: 'external' | 'run',
@@ -108,6 +113,7 @@ export function defineTool({
   cacheWithinQuery = false,
   mayMutateWorkspaceAfterReturn = false,
   isDestructive = () => false,
+  duplicateCallPolicy = () => 'warn',
   errorOutput = 'json-error-envelope',
   mcpServer,
   sideEffectScope = 'external',
@@ -126,6 +132,7 @@ export function defineTool({
     cacheWithinQuery,
     mayMutateWorkspaceAfterReturn,
     isDestructive,
+    duplicateCallPolicy,
     errorOutput,
     sideEffectScope,
   };

package/yeaft/tools/wait-agent.js

@@ -19,7 +19,7 @@
  *              processing. The envelope flags `runningInBackground:
  *              true` (the sub-agent IS continuing — it does NOT need
  *              another PromptAgent to keep going) and recommends either
- *              another WaitAgent or CloseAgent. `result` carries the
+ *              another bounded WaitAgent or CloseAgent. `result` carries the
  *              mid-stream preview (the driver keeps lastResult fresh
  *              from every text_delta).
  *
@@ -43,7 +43,7 @@ import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
  * otherwise eat tail-positioned nudges when `result` is long).
  *
  * @param {string} status
- * @param {{ timedOut?: boolean, runningInBackground?: boolean, budgetExceeded?: boolean, stale?: boolean }} [opts]
+ * @param {{ timedOut?: boolean, budgetExceeded?: boolean, stale?: boolean, mustCollectReply?: boolean }} [opts]
  */
 function nextStepsFor(status, opts = {}) {
   if (opts.budgetExceeded) {
@@ -63,6 +63,15 @@ function nextStepsFor(status, opts = {}) {
       'task and start a fresh agent if needed.'
     );
   }
+  if (opts.timedOut && opts.mustCollectReply) {
+    return (
+      'The PromptAgent follow-up reply is still pending and must be collected ' +
+      'in this parent turn. Call WaitAgent again with a larger bounded timeout. ' +
+      'Do not end the turn or switch to ListAgents/notifications. Stop re-waiting ' +
+      'only if the agent becomes stale/stalled, the wait is cancelled, or the ' +
+      'agent returns idle/terminal.'
+    );
+  }
   if (opts.timedOut) {
     return (
       'Sub-agent is running in the background; it does not need another ' +
@@ -129,6 +138,11 @@ function errorNextSteps() {
  */
 function buildEnvelope(agent, { timedOut = false } = {}) {
   const status = agent.status;
+  const mustCollectReply = agent.promptReplyPending === true;
+  if (!timedOut && (status === STATUS.IDLE || isTerminalAgentStatus(status))) {
+    agent.promptReplyPending = false;
+    agent.promptReplyPendingAt = null;
+  }
   const liveness = diagnoseAgentLiveness(agent);
   const budgetResult = agent.result && typeof agent.result === 'object'
     && agent.result.status === 'budget_exceeded'
@@ -140,7 +154,12 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
         ? agent.result
         : (agent.lastResult || ''));
   const env = {
-    next_steps: nextStepsFor(status, { timedOut, budgetExceeded: !!budgetResult, stale: liveness.stale }),
+    next_steps: nextStepsFor(status, {
+      timedOut,
+      budgetExceeded: !!budgetResult,
+      stale: liveness.stale,
+      mustCollectReply: mustCollectReply && !liveness.stale,
+    }),
     agentId: agent.id,
     name: agent.name,
     status,
@@ -154,6 +173,7 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     diagnostic: liveness.diagnostic,
     messages: Array.isArray(agent.messages) ? agent.messages.length : 0,
     turns: agent.usage?.turns || 0,
+    mustCollectReply: timedOut ? mustCollectReply : false,
   };
   if (timedOut) {
     env.timedOut = true;
@@ -192,15 +212,15 @@ Status semantics:
     another PromptAgent. Either WaitAgent again with a larger timeout,
     CloseAgent to cut it short, or tell the user it's still working.
 
-CRITICAL — after WaitAgent returns you MUST take one of these actions:
-  • status terminal: relay/retry/report.
-  • status idle:     reply to user OR PromptAgent OR CloseAgent.
-  • timedOut:        re-wait, cut short, or report progress.
-NEVER end your turn silently right after WaitAgent — the user has not seen
-the sub-agent's reply yet; only you have. The orchestration loop is
-SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
+After WaitAgent returns, act on the status. A non-stale timeout after PromptAgent
+has 'mustCollectReply=true': call WaitAgent again with a larger bounded timeout in
+the same parent turn until idle/terminal. A stale/stalled agent breaks that loop:
+inspect/report/close it instead. For ordinary SpawnAgent background work, use
+ListAgents or later completion notifications instead of repeatedly re-waiting.
 
-Compatibility tool. The default wait is a short 5000ms poll. Callers may request up to 300000ms (5 minutes), but this is no longer the primary sub-agent workflow; prefer SpawnAgent + ListAgents + completion notifications for async background work.`,
+The default wait is a bounded 5000ms poll; callers may request up to 300000ms
+(5 minutes). Never use an unbounded blind loop: every wait is capped, liveness is
+checked after each timeout, and stale/stalled is the explicit stop condition.`,
     zh: `等待子 Agent 的下一次状态变更（turn 结束、终止或等待超时）并获取状态信封。
 
 返回 JSON，含明确的 status、最新的 result 文本、liveness 计数器（toolUseCount、tokenCount、
@@ -215,11 +235,13 @@ msSinceLastEvent、recentTools）、可随时 Read 的持久化 outputFile 路
     仍在运行。不需要再 PromptAgent。要么用更大 timeout 再次 WaitAgent，要么 CloseAgent 中断，
     要么告知用户它仍在工作。
 
+PromptAgent 后若非 stale/stalled 的有界等待超时，必须在同一父级 turn 使用更大的有界 timeout
+再次调用 WaitAgent，直到 idle/terminal；不要改用 ListAgents/notification 丢下未收集的回复。
 关键——如果信封显示 stale/stalled，子 Agent 可能卡死或空转。不要反复调用 WaitAgent——向用户
 报告情况，决定是 CloseAgent（带 close_reason）还是重试。
 
-此工具保留用于向后兼容。现代异步流程请用 ListAgents 做非阻塞状态检查，依赖 turn 开始时的
-notification 获取完成事件。`
+普通 SpawnAgent 异步流程仍用 ListAgents 做非阻塞状态检查，并依赖后续 completion
+notification；不要对普通后台任务盲目循环等待。每次等待都有上限，stale/stalled 是停止条件。`
   },
   parameters: {
     type: 'object',
@@ -247,6 +269,7 @@ notification 获取完成事件。`
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input, ctx) {
     const { agent_id, timeout_ms = 5000 } = input;
     if (!agent_id) {
@@ -297,6 +320,13 @@ notification 获取完成事件。`
       await new Promise(r => setTimeout(r, 200));
     }
 
+    // Re-check after the final sleep. The status may have changed just before
+    // the deadline without another loop iteration.
+    if (isTerminalAgentStatus(agent.status) || agent.status === STATUS.IDLE) {
+      consumeNotificationForAgent(agent.id);
+      return JSON.stringify(buildEnvelope(agent));
+    }
+
     // Wait elapsed; the sub-agent is still running. Surface mid-stream
     // preview + liveness so the parent has actionable signal.
     return JSON.stringify(buildEnvelope(agent, { timedOut: true }));

package/yeaft/tools/web-fetch.js

@@ -42,7 +42,8 @@ Use this to read documentation, articles, or any web page.
 
 Guidelines:
 - Provide the full URL including protocol (https://)
-- Large pages will be truncated — use the offset parameter for pagination
+- Fetch one authoritative relevant page first; inspect it before fetching alternatives
+- Set max_length to the smallest useful content budget. Large pages are truncated; use a more targeted source rather than repeatedly fetching the same URL
 - For APIs, the raw response body is returned as-is
 - Respects the abort signal for cancellation`,
     zh: `获取并读取网页内容。
@@ -51,7 +52,8 @@ Guidelines:
 
 使用指南：
 - 提供完整 URL 含协议（https://）
-- 大页面会截断——用 offset 参数做分页
+- 先抓取一个最权威、最相关的页面；检查结果后再决定是否抓取备选页面
+- 将 max_length 设为满足需要的最小内容预算。大页面会截断；应改用更定向的来源，而不是重复抓取同一 URL
 - 对 API 请求，原始响应体原样返回
 - 尊重取消信号`
   },

package/yeaft/tools/web-search.js

@@ -32,17 +32,17 @@ Use this when you need up-to-date information that may not be in your training d
 Returns search results with titles, URLs, and snippets.
 
 Guidelines:
-- Use specific, targeted search queries
+- Use one specific, targeted query with the smallest useful result limit; inspect it before trying alternatives
 - Include the current year for time-sensitive queries
-- Combine with WebFetch to read full page content from results`,
+- Fetch the most authoritative relevant result first. Add another source only when the claim is consequential, disputed, stale, or not established by the first source`,
     zh: `搜索网页获取最新信息。
 
 当你需要训练数据中可能没有的最新信息时使用。返回搜索结果，含标题、URL 和摘要。
 
 使用指南：
-- 使用具体、有针对性的搜索关键词
+- 先执行一个具体、定向的查询，并使用满足需要的最小结果数；检查结果后再决定是否尝试其他查询
 - 时间敏感的查询要包含当前年份
-- 配合 WebFetch 读取搜索结果中的完整页面内容`
+- 优先抓取最权威、最相关的结果。只有结论影响重大、存在争议、可能过时，或首个来源不能证明时才增加来源`
   },
   parameters: {
     type: 'object',

package/yeaft/web-bridge.js

@@ -1349,6 +1349,7 @@ function projectPersistedToHistoryEntry(m, { includeReflections = false } = {})
   if (m.turnId) entry.turnId = m.turnId;
   if (m.imageAssetAnchor) entry.imageAssetAnchor = true;
   if (m.responseKind === 'progress' || m.responseKind === 'result') entry.responseKind = m.responseKind;
+  if (Number.isInteger(m.llmCallCount) && m.llmCallCount > 0) entry.llmCallCount = m.llmCallCount;
   if (m.incomplete === true) entry.incomplete = true;
   if (typeof m.stopReason === 'string' && m.stopReason) entry.stopReason = m.stopReason;
   if (m.sessionId) entry.sessionId = m.sessionId;
@@ -1489,6 +1490,7 @@ function projectVisibleHistoryChunkMessages(messages = []) {
       ...(Array.isArray(m.images) && m.images.length > 0 ? { images: m.images } : {}),
       ...(m.speakerVpId ? { speakerVpId: m.speakerVpId } : {}),
       ...(m.responseKind === 'progress' || m.responseKind === 'result' ? { responseKind: m.responseKind } : {}),
+      ...(Number.isInteger(m.llmCallCount) && m.llmCallCount > 0 ? { llmCallCount: m.llmCallCount } : {}),
       ...(m.incomplete === true ? { incomplete: true } : {}),
       ...(typeof m.stopReason === 'string' && m.stopReason ? { stopReason: m.stopReason } : {}),
       ...(Array.isArray(m.todos) ? { todos: m.todos } : {}),