npm - @yeaft/webchat-agent - Versions diffs - 1.0.453 → 1.0.456 - Mend

@yeaft/webchat-agent 1.0.453 → 1.0.456

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/local-runtime/version.json +1 -1
package/local-runtime/web/app.bundle.js +79 -78
package/local-runtime/web/app.bundle.js.gz +0 -0
package/local-runtime/web/index.html +1 -1
package/package.json +1 -1
package/yeaft/debug-trace.js +11 -1
package/yeaft/engine.js +116 -35
package/yeaft/personas.js +2 -2
package/yeaft/prompts.js +11 -6
package/yeaft/sub-agent/liveness.js +8 -1
package/yeaft/templates/personas/explorer.md +2 -2
package/yeaft/templates/personas/researcher.md +2 -2
package/yeaft/templates/plan-instruction.md +2 -2
package/yeaft/tools/activation.js +1 -1
package/yeaft/tools/agent.js +13 -6
package/yeaft/tools/file-read.js +4 -2
package/yeaft/tools/glob.js +2 -0
package/yeaft/tools/grep.js +6 -4
package/yeaft/tools/list-agents.js +1 -0
package/yeaft/tools/read-task-log.js +1 -0
package/yeaft/tools/send-message.js +20 -14
package/yeaft/tools/skill.js +1 -0
package/yeaft/tools/start-plan.js +4 -4
package/yeaft/tools/todo-write.js +6 -6
package/yeaft/tools/types.js +7 -0
package/yeaft/tools/wait-agent.js +43 -13
package/yeaft/tools/web-fetch.js +4 -2
package/yeaft/tools/web-search.js +4 -4
package/yeaft/web-bridge.js +2 -0

package/local-runtime/web/app.bundle.js.gz CHANGED Viewed

Binary file

package/local-runtime/web/index.html CHANGED Viewed

@@ -16,6 +16,6 @@
 </head>
 <body>
   <div id="app"></div>
-  <script type="module" src="app.bundle.js?v=1ef42512"></script>
+  <script type="module" src="app.bundle.js?v=1ad1700c"></script>
 </body>
 </html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.453",
+  "version": "1.0.456",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/debug-trace.js CHANGED Viewed

@@ -1025,6 +1025,7 @@ function traceToolToLegacy(trace, tool) {
     tool_call_id: tool.toolCallId || null,
     duration_ms: tool.durationMs || 0,
     is_error: tool.isError ? 1 : 0,
+    suppressed: !!tool.suppressed,
     created_at: tool.createdAt || trace.openedAt || 0,
   };
 }
@@ -1305,7 +1306,15 @@ export class DebugTrace {
     this.#appendTraceRecord(trace, 'loop', loop, { writeMeta: !trace.active });
   }
-  logTool(turnId, { toolName, toolCallId = null, toolInput = null, toolOutput = null, durationMs = null, isError = false } = {}) {
+  logTool(turnId, {
+    toolName,
+    toolCallId = null,
+    toolInput = null,
+    toolOutput = null,
+    durationMs = null,
+    isError = false,
+    suppressed = false,
+  } = {}) {
     const id = randomUUID();
     const ctx = this.#turnIndex.get(turnId);
     if (!ctx) return id;
@@ -1322,6 +1331,7 @@ export class DebugTrace {
       toolOutput: truncateText(toolOutput == null ? null : String(toolOutput), this.#textMaxBytes),
       durationMs: Number(durationMs || 0),
       isError: !!isError,
+      suppressed: !!suppressed,
       createdAt: Date.now(),
     };
     trace.tools.push(tool);

package/yeaft/engine.js CHANGED Viewed

@@ -2420,6 +2420,11 @@ export class Engine {
     let lastT1AtToolCount = 0;
     let arcStartIdx = turnStartIdx + 1;
     let t1CollapsesDone = 0;
+    // Duplicate policy is scoped to one user query. Only successful, real
+    // executions increment these counters; errors and cache reuse do not.
+    const queryDuplicateCounts = new Map();
+    const queryDuplicateSuppressions = new Map();
+    let duplicateReminderAwaitingResponse = false;
     const queryNumber = (this.#__queryCounter = (this.#__queryCounter || 0) + 1);
     // feat-6af5f9f1 PR B: a Turn = one user prompt + all AI responses.
@@ -2894,7 +2899,7 @@ export class Engine {
             commitDispatch();
           },
         });
-        yield { type: 'turn_start', turnNumber, threadId };
+        yield { type: 'turn_start', turnId: queryTurnId, turnNumber, threadId };
         // Provider iteration begins after the visible boundary. Native adapters
         // commit in onRequestStart immediately before fetch. A plain legacy
@@ -3546,6 +3551,23 @@ export class Engine {
       fullResponseText += responseText;
       // ─── Handle max_tokens → auto-continue ────────────
+      // A suppressed call leaves a synthetic reminder as the latest user
+      // message. Some models answer it with an empty end_turn. Continue exactly
+      // once so suppression cannot silently abandon the user's task.
+      if (duplicateReminderAwaitingResponse) {
+        if (responseText.trim() || toolCalls.length > 0) {
+          duplicateReminderAwaitingResponse = false;
+        } else {
+          duplicateReminderAwaitingResponse = false;
+          conversationMessages.push({
+            role: 'user',
+            content: '[system note] The duplicate tool call was suppressed, but the current user task is still active. Continue toward the requested outcome using the prior result or a different action; do not end the turn solely because the duplicate was blocked.',
+          });
+          yield { type: 'turn_end', turnNumber, stopReason: 'duplicate_tool_continue', threadId };
+          continue;
+        }
+      }
       if (stopReason === 'max_tokens' && continueTurns < MAX_CONTINUE_TURNS) {
         continueTurns++;
         // This synthetic continuation is part of the model-visible protocol.
@@ -3922,6 +3944,16 @@ export class Engine {
       let abortedDuringTools = false;
       /** @type {string[]} */
       const pendingDupReminders = [];
+      let terminateAfterDuplicateBatch = false;
+      const duplicatePolicyForCall = (toolCall) => {
+        const toolDef = this.#toolRegistry
+          ? this.#toolRegistry.get(toolCall.name)
+          : this.#tools.get(toolCall.name);
+        const requested = typeof toolDef?.duplicateCallPolicy === 'function'
+          ? toolDef.duplicateCallPolicy(toolCall.input)
+          : 'warn';
+        return ['allow', 'warn', 'suppress'].includes(requested) ? requested : 'warn';
+      };
       /**
        * Completed executions waiting for their original-order commit. Starting
        * a bounded read-only segment together removes wall-clock latency without
@@ -3977,6 +4009,7 @@ export class Engine {
         if (!preparedParallelExecution && !toolBatchBarrier && !signal?.aborted
             && toolAllowedForRequest(tc) && isConcurrencySafeTool(this, tc.name, tc.input)
+            && duplicatePolicyForCall(tc) !== 'suppress'
             && !mayMutateWorkspaceAfterReturn(this, tc.name, tc.input)) {
           const parallelCalls = [];
           const segmentCacheKeys = new Set();
@@ -3986,6 +4019,7 @@ export class Engine {
             const candidate = toolCalls[candidateIndex];
             if (!toolAllowedForRequest(candidate)
                 || !isConcurrencySafeTool(this, candidate.name, candidate.input)
+                || duplicatePolicyForCall(candidate) === 'suppress'
                 || mayMutateWorkspaceAfterReturn(this, candidate.name, candidate.input)) break;
             const candidateKey = `${candidate.name}\u001f${argsHashOf(candidate.input)}`;
             const candidateCacheable = isCacheableTool(this, candidate.name, candidate.input);
@@ -4048,36 +4082,14 @@ export class Engine {
           || (activeToolBatchBarrier != null && !readyParallelExecution);
         const toolStartTime = readyParallelExecution?.startedAt || Date.now();
-        // PR-L: duplicate-call detection. If this exact (toolName,
-        // argsHash) pair has already been executed DUP_TOOL_THRESHOLD
-        // (3) times within the current turn + last 2 turns, queue a
-        // system reminder. We push the reminder AFTER the tool batch
-        // completes (not now) so the
-        // assistant(tool_use) → user(tool_result, …) pairing demanded
-        // by the Anthropic / OpenAI Responses APIs stays intact. We
-        // don't block the call — the LLM still decides.
-        if (!skipped) {
-          const dupHash = argsHashOf(tc.input);
-          // PR-L follow-up: lookback is by user-conversation turn
-          // (`queryNumber`), NOT by inner adapter loop iteration. Each call
-          // to query() bumps queryNumber once, so "last 2 turns" means the
-          // current user turn + the previous two user turns — the natural
-          // semantic for "the model is stuck in a loop across the
-          // conversation."
-          const dupInfo = this.#execLog.dupInfo({
-            toolName: tc.name,
-            argsHash: dupHash,
-            currentTurn: queryNumber,
-            lookbackTurns: 2,
-          });
-          if (dupInfo.count + 1 >= DUP_TOOL_THRESHOLD) {
-            pendingDupReminders.push(buildDuplicateReminder({
-              toolName: tc.name,
-              count: dupInfo.count + 1,
-              lastResultBrief: dupInfo.lastResultBrief,
-            }));
-          }
-        }
+        const dupHash = argsHashOf(tc.input);
+        const duplicateCallKey = `${tc.name}:${dupHash}`;
+        const duplicateCallPolicy = duplicatePolicyForCall(tc);
+        const successfulDuplicateCount = queryDuplicateCounts.get(duplicateCallKey) || 0;
+        const duplicateCallSuppressed = !skipped
+          && duplicateCallPolicy === 'suppress'
+          && successfulDuplicateCount >= DUP_TOOL_THRESHOLD - 1;
+        let suppressionCount = queryDuplicateSuppressions.get(duplicateCallKey) || 0;
         let output;
         let displayImages = [];
@@ -4179,6 +4191,24 @@ export class Engine {
             sourceToolName: tc.name,
           };
           yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, skipped: true, threadId: this.currentThreadId };
+        } else if (duplicateCallSuppressed) {
+          suppressionCount += 1;
+          queryDuplicateSuppressions.set(duplicateCallKey, suppressionCount);
+          const dupInfo = this.#execLog.dupInfo({
+            toolName: tc.name,
+            argsHash: dupHash,
+            currentTurn: queryNumber,
+            lookbackTurns: 0,
+          });
+          pendingDupReminders.push(buildDuplicateReminder({
+            toolName: tc.name,
+            count: successfulDuplicateCount + suppressionCount,
+            lastResultBrief: dupInfo.lastResultBrief,
+          }));
+          if (suppressionCount >= DUP_TOOL_THRESHOLD) terminateAfterDuplicateBatch = true;
+          output = `Suppressed duplicate call: ${tc.name} returned a stable result twice with these arguments in this turn. Reuse the previous result or choose a different action.`;
+          yield { type: 'tool_start', id: tc.id, name: tc.name, input: tc.input, threadId: this.currentThreadId };
+          yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: false, suppressed: true, threadId: this.currentThreadId };
         } else {
           duplicateKey = `${tc.name}\u001f${argsHashOf(tc.input)}`;
           cacheableTool = isCacheableTool(this, tc.name, tc.input);
@@ -4280,6 +4310,24 @@ export class Engine {
         currentToolCallForAsyncTask = null;
+        if (!skipped && !duplicateCallSuppressed && !isError && !reusedReadOnlyResult
+            && duplicateCallPolicy !== 'allow') {
+          const nextDuplicateCount = successfulDuplicateCount + 1;
+          queryDuplicateCounts.set(duplicateCallKey, nextDuplicateCount);
+          if (duplicateCallPolicy === 'warn' && nextDuplicateCount === DUP_TOOL_THRESHOLD) {
+            const dupInfo = this.#execLog.dupInfo({
+              toolName: tc.name,
+              argsHash: dupHash,
+              currentTurn: queryNumber,
+              lookbackTurns: 0,
+            });
+            pendingDupReminders.push(buildDuplicateReminder({
+              toolName: tc.name,
+              count: nextDuplicateCount,
+              lastResultBrief: dupInfo.lastResultBrief,
+            }));
+          }
+        }
         const toolDurationMs = readyParallelExecution?.durationMs ?? (Date.now() - toolStartTime);
         // feat-6af5f9f1 PR B: emit a structured `tool_exec` event for the
@@ -4294,6 +4342,7 @@ export class Engine {
           name: tc.name,
           durationMs: toolDurationMs,
           isError,
+          suppressed: duplicateCallSuppressed,
           toolOutput: output,
           ...(reusedReadOnlyResult ? { reused: true, reusedCallId: reusedReadOnlyCallId } : {}),
           ...(skipped ? { skipped: true } : {}),
@@ -4303,7 +4352,8 @@ export class Engine {
         // 2026-05-13: feed the per-tool counters. Stays best-effort — a
         // stats sink that throws shouldn't crash the engine. `record`
         // already swallows internal write errors.
-        if (!skipped && this.#toolStats && typeof this.#toolStats.record === 'function') {
+        if (!skipped && !duplicateCallSuppressed
+            && this.#toolStats && typeof this.#toolStats.record === 'function') {
           try {
             this.#toolStats.record({
               name: tc.name,
@@ -4322,15 +4372,17 @@ export class Engine {
           toolOutput: output,
           durationMs: toolDurationMs,
           isError,
+          suppressed: duplicateCallSuppressed,
           skipped,
           reused: reusedReadOnlyResult,
           reusedCallId: reusedReadOnlyCallId,
         });
-        if (!skipped && !reusedReadOnlyResult && tc.name === 'StartPlan') {
+        if (!skipped && !duplicateCallSuppressed && !reusedReadOnlyResult && tc.name === 'StartPlan') {
           planBootstrapPending = true;
         }
-        if (!skipped && !reusedReadOnlyResult && !readOnlyToolReuseDisabled && cacheableTool) {
+        if (!skipped && !duplicateCallSuppressed && !reusedReadOnlyResult
+            && !readOnlyToolReuseDisabled && cacheableTool) {
           readOnlyToolResults.set(duplicateKey, {
             output,
             isError,
@@ -4372,7 +4424,7 @@ export class Engine {
         // user-conversation turn), not the inner loop's turnNumber.
         // Aligns exec-log layout with dup detection lookback and the
         // T2 fallback-stub readTurn() call below.
-        if (!skipped) {
+        if (!skipped && !duplicateCallSuppressed) {
           this.#execLog.append(queryNumber, buildExecLogEntry({
             loopIdx: queryToolCount,
             toolName: tc.name,
@@ -4392,6 +4444,23 @@ export class Engine {
       for (const reminder of pendingDupReminders) {
         conversationMessages.push({ role: 'user', content: reminder });
       }
+      if (pendingDupReminders.length > 0) duplicateReminderAwaitingResponse = true;
+      if (terminateAfterDuplicateBatch) {
+        yield {
+          type: 'error',
+          error: 'Terminated repeated duplicate tool calls after bounded suppression attempts.',
+          code: 'duplicate_tool_loop',
+          retryable: false,
+        };
+        yield {
+          type: 'turn_end',
+          turnNumber,
+          stopReason: 'duplicate_tool_loop',
+          threadId,
+          terminal: true,
+        };
+        break;
+      }
       // A plan bootstrap that produced only a TodoWrite has no executable work
       // to feed back to the provider. Close it here. This is intentionally
@@ -4616,6 +4685,18 @@ export class Engine {
       // Loop back to call adapter again with tool results
     }
+    // Store the final provider-call count on the response row itself. Debug
+    // events are transient; the response card must retain the count after a
+    // reload without inventing a second counter.
+    const llmCountMessage = lastPersistedAssistantTextMessage || lastPersistedAssistantMessage;
+    if (llmCountMessage && typeof this.#conversationStore?.update === 'function') {
+      const updated = this.#conversationStore.update(llmCountMessage, {
+        llmCallCount: turnNumber,
+      });
+      if (updated?.id === lastPersistedAssistantTextMessage?.id) lastPersistedAssistantTextMessage = updated;
+      if (updated?.id === lastPersistedAssistantMessage?.id) lastPersistedAssistantMessage = updated;
+    }
     // feat-6af5f9f1 PR B: turn closed. Emits final totals so the debug
     // panel can show "Turn done · 4 loops · 12.4s · 5.0k tok" without
     // having to reduce the loops itself. Always fires (every break path

package/yeaft/personas.js CHANGED Viewed

@@ -37,12 +37,12 @@ let cached = null;
  * @returns {{ meta: object, body: string }}
  */
 export function parseFrontmatter(source) {
-  const match = source.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return { meta: {}, body: source };
   const [, yaml, body] = match;
   const meta = {};
-  const lines = yaml.split('\n');
+  const lines = yaml.split(/\r?\n/);
   let currentKey = null;
   let currentList = null;

package/yeaft/prompts.js CHANGED Viewed

@@ -462,8 +462,8 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
   },
   {
     tools: ['FileRead', 'FileWrite', 'FileEdit', 'Glob', 'Grep', 'ListDir', 'ApplyPatch', 'NotebookEdit'],
-    en: 'Read existing files before editing. Use dedicated file/search tools instead of shell search or `sed -i`; make small, reviewable edits and batch independent reads.',
-    zh: '编辑前先读现有文件。文件搜索和修改优先使用专用工具，不用 shell 搜索或 `sed -i`；改动保持小而可审查，独立读取应并行发出。',
+    en: 'Read existing files before editing. Use dedicated file/search tools instead of shell search or `sed -i`; make small, reviewable edits. Parallelize only proven-independent reads under the accuracy-first rule above.',
+    zh: '编辑前先读现有文件。文件搜索和修改优先使用专用工具，不用 shell 搜索或 `sed -i`；改动保持小而可审查。只有明确满足上述准确性优先判据的读取才可并行。',
   },
   {
     tools: ['Bash'],
@@ -472,13 +472,13 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
   },
   {
     tools: ['TodoWrite'],
-    en: 'For non-trivial multi-step work, write a brief visible plan and call `TodoWrite` in the same assistant response as the first independent work tools. Do not spend a separate model round entering planning mode, and do not stop after planning unless user input genuinely blocks the first step.',
-    zh: '非平凡多步骤任务先写简短可见计划，并在同一个 assistant response 中把 `TodoWrite` 与第一批独立工作工具一起发出。不要用单独的模型回合进入规划模式；只有用户信息确实阻塞第一步时才在规划后停下。',
+    en: 'For non-trivial multi-step work, write a brief visible plan and call `TodoWrite` in the same assistant response as the first necessary work-tool call only when its arguments and safety do not depend on another result. Start with the smallest such call; do not speculative-batch the investigation or stop after planning unless user input genuinely blocks the first step.',
+    zh: '非平凡多步骤任务先写简短可见计划。只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 `TodoWrite` 一起发出；先执行满足条件的最小调用，不要推测性批量展开调查。只有用户信息确实阻塞第一步时才在规划后停下。',
   },
   {
     tools: ['SpawnAgent', 'PromptAgent', 'WaitAgent', 'CloseAgent', 'ListAgents'],
-    en: 'Delegate only independent, bounded work. Keep ownership in the parent, avoid polling loops, and close sub-agents after collecting their result.',
-    zh: '只委派边界清晰且独立的工作。父级保留任务所有权，不要循环轮询，取得结果后关闭子 Agent。',
+    en: 'Delegate only independent, bounded work. Keep ownership in the parent. After PromptAgent queues follow-up work, call WaitAgent in the same parent turn and collect the reply before ending. If a bounded wait times out, wait again with a larger bound unless the agent is stale/stalled. Relay the reply or continue the dependent work, then close the sub-agent when it is no longer needed.',
+    zh: '只委派边界清晰且独立的工作。父级保留任务所有权。PromptAgent 排队后续工作后，必须在同一个父级 turn 调用 WaitAgent 并拿到回复再结束；有界等待超时后，除非 Agent 已 stale/stalled，否则使用更大上限继续等待；随后转述结果或继续依赖该结果的工作，不再需要时关闭子 Agent。',
   },
   {
     tools: ['ListTasks', 'ReadTaskLog', 'CancelTask'],
@@ -500,6 +500,11 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
 function renderActiveToolGuidance(toolNames, language) {
   const active = new Set(Array.isArray(toolNames) ? toolNames : []);
   const lines = [];
+  if (active.size > 0) {
+    lines.push(language === 'zh'
+      ? '- 准确性优先：先用能解决当前未知的最小定向调用。只有每个调用都已经确定有必要，且其参数和安全性都不依赖同批其他结果时，才在一个响应中发出多个工具调用；否则串行执行。不要推测性扇出、重复成功的读取/搜索，也不要默认抓取多个来源；先检查证据，再决定是否扩展。'
+      : '- Accuracy first: start with the smallest targeted call that can resolve the current uncertainty. Issue multiple tool calls in one response only when every call is already necessary and its arguments and safety do not depend on another call\'s result. Otherwise run them sequentially. Do not fan out speculatively, repeat a successful read/search, or fetch multiple sources by default; inspect evidence before expanding.');
+  }
   for (const group of TOOL_GUIDANCE_GROUPS) {
     if (!group.tools.some(name => active.has(name))) continue;
     lines.push(`- ${language === 'zh' ? group.zh : group.en}`);

package/yeaft/sub-agent/liveness.js CHANGED Viewed

@@ -117,7 +117,14 @@ export function diagnoseAgentLiveness(agent, opts = {}) {
     : DEFAULT_STALL_THRESHOLD_MS;
   const liveness = snapshotLiveness(agent?.liveness, now);
   const fallbackAt = agent?.createdAt || agent?.usage?.startedAt || null;
-  const activityAt = liveness.lastEventAt || fallbackAt;
+  // Queueing a PromptAgent continuation starts a new collection window. Do not
+  // diagnose that fresh follow-up as stale merely because the retained child
+  // last emitted an event during an older turn.
+  const activityAt = Math.max(
+    liveness.lastEventAt || 0,
+    fallbackAt || 0,
+    agent?.promptReplyPendingAt || 0,
+  ) || null;
   const msSinceActivity = activityAt ? Math.max(0, now - activityAt) : null;
   const stale = agent?.status === 'running'
     && msSinceActivity !== null

package/yeaft/templates/personas/explorer.md CHANGED Viewed

@@ -19,7 +19,7 @@ You are a fast, read-only **Explorer** sub-agent. Your job is to scout the codeb
 ## Operating Principles
 - **Read-only**: Never modify files, run bash, or spawn agents.
-- **Be fast**: Use `Grep` / `Glob` / `ListDir` to narrow the search, then `Read` only the needed ranges.
+- **Be targeted**: Use one focused `Grep` / `Glob` / `ListDir` call to narrow the search, inspect it, then `Read` only the ranges still needed. Do not speculative-batch alternative searches.
 - **Be specific**: Return concrete file paths, line numbers, and short excerpts.
 - **Respect the contract**: Match your output to the `expected_output` schema exactly.
@@ -36,7 +36,7 @@ Structured. Bullet points. File paths as backticked references with `path:line`.
 ## 操作原则
 - **只读**：不要修改文件，不要运行 bash，不要派生 Agent。
-- **要快**：先用 `Grep` / `Glob` / `ListDir` 缩小范围，再只 `Read` 必要行段。
+- **要定向**：先执行一个聚焦的 `Grep` / `Glob` / `ListDir` 调用缩小范围，检查结果后再只 `Read` 仍然必要的行段。不要推测性批量发出备选搜索。
 - **要具体**：返回明确的文件路径、行号和短摘录。
 - **遵守契约**：输出必须严格匹配 `expected_output` schema。

package/yeaft/templates/personas/researcher.md CHANGED Viewed

@@ -18,7 +18,7 @@ You are a **Researcher** sub-agent. Your job is to gather information from the w
 ## Operating Principles
 - **Cite sources**: Every factual claim must link back to a URL or doc path.
-- **Triangulate**: Prefer multiple independent sources over one.
+- **Validate proportionally**: Start with the most authoritative relevant source. Add another source only when the claim is consequential, disputed, stale, or not established by the first source; do not fetch multiple sources by default.
 - **Summarize**: Return digest-form findings, not raw dumps.
 - **Track freshness**: Note publication dates when recency matters.
@@ -35,7 +35,7 @@ Short synthesis first, then bulleted sources with one-line summaries. No filler.
 ## 操作原则
 - **引用来源**：每个事实性判断都必须能回链到 URL 或文档路径。
-- **交叉验证**：优先使用多个独立来源，而不是只依赖一个来源。
+- **按风险验证**：先查最权威、最相关的来源。只有结论影响重大、存在争议、可能过时，或首个来源不能证明时才增加来源；不要默认抓取多个来源。
 - **做综合**：返回摘要式发现，不要倾倒原始材料。
 - **关注时效**：当新旧会影响判断时，标明发布时间。

package/yeaft/templates/plan-instruction.md CHANGED Viewed

@@ -17,7 +17,7 @@ You have just entered **planning mode** for the topic below. Your job is to thin
 1. Write a short prose plan: problem, approach, risks.
 2. Call `TodoWrite` with the ordered steps. Mark exactly one item as `in_progress`.
-3. If the first-step tools and arguments are already known, emit `TodoWrite` and those independent tool calls in the same assistant response. Otherwise wait only for a result that genuinely determines the next action.
+3. Emit `TodoWrite` with a first work-tool call in the same assistant response only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call. If its result can change the next action, inspect it before issuing more calls; do not speculative-batch the investigation.
 If the first step is to ask the user a blocking question, ask it and stop. Otherwise keep moving.
@@ -40,6 +40,6 @@ If the first step is to ask the user a blocking question, ask it and stop. Other
 1. 写一段简短计划：问题、方案、风险。
 2. 调用 `TodoWrite` 写入有序步骤，并且只能把一个条目标记为 `in_progress`。
-3. 如果第一步所需的工具和参数已经确定，应在同一个 assistant response 中发出 `TodoWrite` 和这些彼此独立的工具调用；否则只在确实需要某个结果来决定下一动作时等待。
+3. 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 `TodoWrite` 一起发出。先执行满足条件的最小调用；如果它的结果可能改变下一动作，应先检查结果，不要推测性批量展开调查。
 如果第一步是向用户询问阻塞问题，那就提问并停下。否则继续推进。

package/yeaft/tools/activation.js CHANGED Viewed

@@ -52,7 +52,7 @@ export const CONDITIONAL_BUILTIN_TOOL_NAMES = new Set([
   'RouteForward',
   'CreateWorkItem',
   // Legacy compatibility only. New planning is a single provider response:
-  // visible prose + TodoWrite + the first independent work tools. Keeping the
+  // visible prose + TodoWrite + the first justified work-tool call. Keeping the
   // definition registered lets old direct callers resolve it without paying a
   // dedicated StartPlan -> provider -> TodoWrite round trip on every new task.
   'StartPlan',

package/yeaft/tools/agent.js CHANGED Viewed

@@ -239,11 +239,15 @@ Async orchestration:
   2. Continue    — keep working in the parent VP; do not block just to poll.
   3. ListAgents  — non-blocking status check when you need progress/liveness.
   4. PromptAgent — optional follow-up if the sub-agent is idle and needs guidance.
+     After queueing it, call WaitAgent in the same parent turn and collect the
+     reply before ending. If a bounded wait times out, wait again with a larger
+     bound unless the agent is stale/stalled.
   5. CloseAgent  — stop or finalize a sub-agent when it is no longer needed.
 Completion/failure is delivered through sub-agent notifications on later parent
-turns. WaitAgent remains available only as a short compatibility poll; do not
-use it as the default workflow or call it repeatedly in a loop.`,
+turns, so do not call WaitAgent merely to poll a newly spawned running agent.
+After PromptAgent follow-up, however, the answer is required to complete that
+workflow; use bounded WaitAgent calls and inspect liveness instead of blind loops.`,
     zh: `创建一个子 Agent 并行处理独立任务。
 子 Agent 在独立上下文中运行，可给定具体 mission 和可选的 expected_output schema。
@@ -263,11 +267,14 @@ use it as the default workflow or call it repeatedly in a loop.`,
   1. SpawnAgent  — 启动子 Agent 作为后台任务并立即返回。
   2. Continue    — 父 VP 继续工作；不要仅仅为了轮询而阻塞。
   3. ListAgents  — 需要进度信息时的非阻塞状态检查。
-  4. WaitAgent   — 短轮询（<5s）或仅在真正需要结果时才明确长等待。
-  5. CloseAgent  — 完成后销毁子 Agent。
+  4. PromptAgent — 子 Agent 空闲且需要指导时，可选发送后续提示。
+     排队后必须在同一个父级 turn 调用 WaitAgent 并拿到回复再结束；有界等待超时后，除非 Agent
+     已 stale/stalled，否则使用更大的有界 timeout 再次等待。
+  5. CloseAgent  — 不再需要时停止或结束子 Agent。
-不要在循环中无终止条件地调用 WaitAgent。如果短检查后子 Agent 仍在运行，继续前进，
-让 notification 在下个 turn 告知你。`
+完成或失败会通过之后父级 turn 的 notification 送达，因此不要为了轮询刚创建且仍运行的
+Agent 调用 WaitAgent。但 PromptAgent 后续工作必须拿到答案才算完成；使用有界 WaitAgent 调用并检查
+liveness，不要盲目循环。`
   },
   parameters: {
     type: 'object',

package/yeaft/tools/file-read.js CHANGED Viewed

@@ -88,7 +88,8 @@ Supports offset and limit for reading specific portions of large files.
 Guidelines:
 - Use absolute paths when possible
-- A file is "large" only at >3000 lines. Read the whole file by default; only use offset/limit above that threshold or when you already know the exact line range you need.
+- Read only the smallest range that answers the current question. A whole-file read is reasonable only when the file is at most 3000 lines and its full contents are actually needed.
+- Do not repeat a successful read with the same range. Continue only when the truncation marker or inspected content shows that another range is necessary.
 - Binary files are detected by extension and rejected
 - Maximum file size: 10MB
 - Default limit: 3000 lines (matches the "large file = >3000 lines" threshold)`,
@@ -98,7 +99,8 @@ Guidelines:
 使用指南：
 - 尽量使用绝对路径
-- 超过 3000 行才算大文件。默认读完整文件；仅在超过此阈值或已知精确行范围时使用 offset/limit
+- 只读取能回答当前问题的最小范围。只有文件不超过 3000 行且确实需要全部内容时，才适合整文件读取
+- 不要用相同范围重复成功的读取。只有截断标记或已检查的内容表明仍需其他范围时才继续
 - 二进制文件通过扩展名识别并拒绝
 - 最大文件大小：10MB
 - 默认行数限制：3000 行`

package/yeaft/tools/glob.js CHANGED Viewed

@@ -123,6 +123,7 @@ Guidelines:
 - Use "**/" for recursive directory matching
 - Common directories (node_modules, .git, etc.) are skipped
 - Returns file paths relative to the search directory
+- Use the narrowest pattern and smallest useful limit; inspect the result before broadening or issuing alternative searches
 - Limited to 500 results by default`,
     zh: `查找匹配 glob 模式的文件。
@@ -132,6 +133,7 @@ Guidelines:
 - 用 "**/" 进行递归目录匹配
 - 常见目录（node_modules、.git 等）被跳过
 - 返回相对于搜索目录的文件路径
+- 使用最窄的模式和满足需要的最小 limit；先检查结果，再决定是否扩大或发出备选搜索
 - 默认限制 500 条结果`
   },
   parameters: {

package/yeaft/tools/grep.js CHANGED Viewed

@@ -808,9 +808,10 @@ Guidelines:
 - Uses the JavaScript RegExp syntax supported by the running Node.js version
 - Escape special characters such as \\. and \\{
 - Skips symlinks, binary files, invalid UTF-8, and text files larger than 16 MiB
-- Use glob or type filters to narrow the search
+- Use glob or type filters and the smallest useful head_limit to narrow the search
+- Inspect one focused search before broadening or trying alternatives; do not repeat a successful equivalent search
 - Skips common large directories such as node_modules and .git
-- Results are limited to 500 matches by default`,
+- Results are limited to 250 matches by default`,
     zh: `用正则表达式搜索文件内容。
 优先使用 ripgrep (rg) 快速搜索，回退到 Node.js 实现。
@@ -824,9 +825,10 @@ Guidelines:
 - 使用当前 Node.js 版本支持的 JavaScript RegExp 语法
 - 特殊字符需转义，如 \\.、\\{
 - 跳过符号链接、二进制、无效 UTF-8 和超过 16 MiB 的文本文件
-- 用 glob 或 type 过滤缩小搜索范围
+- 用 glob 或 type 过滤，并设置满足需要的最小 head_limit 来缩小搜索范围
+- 先检查一个聚焦搜索的结果，再决定是否扩大或尝试其他搜索；不要重复成功的等价搜索
 - 跳过 node_modules、.git 等常见大目录
-- 默认结果限制 500 条`
+- 默认结果限制 250 条`
   },
   parameters: {
     type: 'object',

package/yeaft/tools/list-agents.js CHANGED Viewed

@@ -58,6 +58,7 @@ stale/stalled 诊断、result 尾部和消息数量。将此作为异步子 Agen
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input, ctx) {
     const includeTerminal = Boolean(input?.include_closed || input?.include_terminal);
     const agents = getAgentRegistry();

package/yeaft/tools/read-task-log.js CHANGED Viewed

@@ -24,6 +24,7 @@ export default defineTool({
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input = {}, ctx = {}) {
     if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
     const taskId = input.taskId;