@yeaft/webchat-agent 1.0.495 → 1.0.496

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.495"}
+{"version":"1.0.496"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.495",
+  "version": "1.0.496",
   "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/sub-agent/execution-control.js

@@ -0,0 +1,90 @@
+/** Sub-agent-local execution policy. No Session config or parent registry is mutated. */
+import { createHash } from 'node:crypto';
+import { ToolRegistry, isToolErrorOutput } from '../tools/registry.js';
+
+/** Defaults are safety ceilings, not targets; explicit positive limits override each field. */
+export function resolveSubAgentBudget(budget, persona) {
+  return {
+    max_tool_calls: persona === 'implementer' ? 128 : 64,
+    wall_time_ms: 15 * 60 * 1000,
+    ...budget,
+  };
+}
+
+export function createExecutionStats() {
+  return { toolCalls: 0, completedCalls: 0, failedCalls: 0, repeatedResults: 0, recentCalls: [], warning: null };
+}
+
+function fingerprint(value) {
+  return createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+}
+
+/**
+ * Structural child-only fence, including aliases and MCP hot registration. The
+ * synchronous reservation precedes execute(), so parallel calls cannot overshoot.
+ * Parent Active Tool Set checks remain independent and must not be bypassed.
+ */
+export class SubAgentToolRegistry extends ToolRegistry {
+  constructor({ allows = () => true, agent = null, stopBudget = null } = {}) {
+    super();
+    this.allows = allows;
+    this.agent = agent;
+    this.stopBudget = stopBudget;
+    this.recentFingerprints = [];
+  }
+
+  register(tool) {
+    if (this.allows(tool)) super.register(tool);
+    return this;
+  }
+
+  async execute(name, input, ctx = {}) {
+    const tool = this.get(name);
+    if (!tool) throw new Error(`Unknown or disallowed child tool: ${name}`);
+    const agent = this.agent;
+    if (!agent) return super.execute(name, input, ctx);
+    // Serial dispatch can resume after a tool_start yield; never start a write
+    // after cancellation, even when the underlying tool ignores AbortSignal.
+    const signal = agent.abortController?.signal;
+    if (signal?.aborted) throw new Error(String(signal.reason || 'Sub-agent aborted'));
+    const stats = agent.execution || (agent.execution = createExecutionStats());
+    const limit = agent.budget?.max_tool_calls;
+    if (limit !== undefined && stats.toolCalls >= limit) {
+      const reason = `max_tool_calls (${limit}) reached; return partial evidence to the parent before extending scope`;
+      this.stopBudget?.(reason);
+      throw new Error(reason);
+    }
+    stats.toolCalls += 1;
+    agent.usage ||= { tokens: 0, turns: 0, startedAt: Date.now() };
+    agent.usage.toolCalls = stats.toolCalls;
+    const entry = { name: tool.name, status: 'running' };
+    stats.recentCalls.push(entry);
+    if (stats.recentCalls.length > 8) stats.recentCalls.shift();
+    if (limit && stats.toolCalls >= Math.ceil(limit * 0.75)) {
+      stats.warning = 'Tool budget nearly exhausted. Collect the current evidence; do not restart the same investigation.';
+    }
+    try {
+      const output = await super.execute(name, input, ctx);
+      const failed = tool.errorOutput === 'json-error-envelope' && isToolErrorOutput(output);
+      entry.status = failed ? 'error' : 'completed';
+      stats.completedCalls += 1;
+      if (failed) stats.failedCalls += 1;
+      // Advisory only: repeated results are not proof of semantic non-progress.
+      // Read ranges, cursors and changed outputs have distinct fingerprints.
+      try {
+        if (tool.isReadOnly?.(input) === true) {
+          const key = fingerprint([tool.name, input, output]);
+          if (this.recentFingerprints.includes(key)) stats.repeatedResults += 1;
+          this.recentFingerprints.push(key);
+          if (this.recentFingerprints.length > 12) this.recentFingerprints.shift();
+        }
+      } catch { /* Advisory instrumentation must never turn a successful tool into a retry. */ }
+      return output;
+    } catch (error) {
+      entry.status = 'error';
+      stats.completedCalls += 1;
+      stats.failedCalls += 1;
+      throw error;
+    }
+  }
+}

package/yeaft/sub-agent/liveness.js

@@ -131,6 +131,13 @@ export function diagnoseAgentLiveness(agent, opts = {}) {
     && msSinceActivity >= thresholdMs;
   return {
     ...liveness,
+    execution: agent?.execution ? {
+      ...agent.execution,
+      recentCalls: agent.execution.recentCalls.map(call => ({ ...call })),
+      remainingToolCalls: Math.max(0, (agent.budget?.max_tool_calls || 0) - agent.execution.toolCalls),
+      limits: agent.budget,
+      progressNote: 'Execution counts and repeated results are diagnostics, not proof of semantic progress or stalling.',
+    } : null,
     msSinceLastEvent: liveness.msSinceLastEvent ?? msSinceActivity,
     stale,
     stalled: stale,

package/yeaft/sub-agent/runner.js

@@ -36,7 +36,8 @@
  */
 
 import { Engine } from '../engine.js';
-import { ToolRegistry } from '../tools/registry.js';
+import { SubAgentToolRegistry, resolveSubAgentBudget, createExecutionStats } from './execution-control.js';
+import { getPersona } from '../personas.js';
 import { buildSpawnedPreamble } from './spawned-prompt.js';
 import { STATUS, isTerminalAgentStatus } from './status.js';
 import { createOutputLog } from './output-log.js';
@@ -83,8 +84,17 @@ const LAST_RESULT_MAX_CHARS = 8 * 1024;
  * @param {ToolRegistry|null} parentRegistry
  * @returns {ToolRegistry}
  */
-export function buildChildToolRegistry(parentRegistry) {
-  const child = new ToolRegistry();
+export function buildChildToolRegistry(parentRegistry, { agent = null, stopBudget = null } = {}) {
+  const preset = agent?.personaData || getPersona(agent?.persona);
+  // Implementers retain work tools; read-only roles are a structural allowlist.
+  // Resolve legacy template names (Read) to canonical FileRead before filtering.
+  const allowed = preset && preset.id !== 'implementer'
+    ? new Set([...preset.tools.map(name => parentRegistry?.get(name)?.name || (name === 'Read' ? 'FileRead' : name)), 'DiscoverTools'])
+    : null;
+  const child = new SubAgentToolRegistry({
+    agent, stopBudget,
+    allows: tool => !RESTRICTED_TOOLS.has(tool.name) && (!allowed || allowed.has(tool.name)),
+  });
   if (!parentRegistry || typeof parentRegistry.getAllTools !== 'function') {
     return child;
   }
@@ -149,7 +159,12 @@ export function startSubAgent(agent, deps = {}) {
     // turns must not pollute the user-facing conversation history. The
     // memory stores are shared so memory recall still works for the
     // sub-agent (matches parent VP persona memory).
-    const childRegistry = buildChildToolRegistry(deps.parentToolRegistry);
+    agent.budget = resolveSubAgentBudget(agent.budget, agent.persona);
+    agent.execution = agent.execution || createExecutionStats();
+    const childRegistry = buildChildToolRegistry(deps.parentToolRegistry, {
+      agent,
+      stopBudget: reason => stopForBudget(agent, reason),
+    });
     subEngine = new Engine({
       adapter: deps.adapter,
       trace: deps.trace,
@@ -193,6 +208,9 @@ export function startSubAgent(agent, deps = {}) {
       parentVpId: deps.parentVpId || null,
       agentName: agent.name,
       mission: agent.mission || agent.task || '',
+      expectedOutput: agent.expected_output,
+      presetPrompt: (agent.personaData || getPersona(agent.persona))?.systemPrompt,
+      budget: agent.budget,
       language: deps.language ?? deps.config?.language ?? 'en',
     });
 
@@ -260,12 +278,21 @@ export function startSubAgent(agent, deps = {}) {
 function buildWallTimeBudgetResult(agent, reason) {
   return {
     status: 'budget_exceeded',
-    partial_output: agent.partial_output || agent.lastResult || agent.result || '',
+    partial_output: agent.partial_output || agent.lastResult
+      || (typeof agent.result === 'string' ? agent.result : agent.result?.partial_output) || '',
     reason,
     usage: { ...(agent.usage || {}) },
   };
 }
 
+function stopForBudget(agent, reason) {
+  if (agent.budgetStopReason || isTerminalAgentStatus(agent.status)) return;
+  agent.budgetStopReason = reason;
+  agent.result = buildWallTimeBudgetResult(agent, reason);
+  agent.partial_output = agent.result.partial_output || '';
+  agent.abortController?.abort(reason);
+}
+
 function armWallTimeWatchdog(agent, deps) {
   const wallTimeMs = agent?.budget?.wall_time_ms;
   if (typeof wallTimeMs !== 'number' || !Number.isFinite(wallTimeMs) || wallTimeMs <= 0) {
@@ -416,10 +443,15 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         continue;
       }
 
+      // Partial evidence belongs to this query, never a previous follow-up.
+      agent.partial_output = '';
+      agent.lastResult = '';
+      agent.result = '';
       let assistantText = '';
       let endedNormally = false;
       let streamError = null;
       const turnTokenStart = agent.liveness?.tokenCount || 0;
+      const priorUsageTokens = agent.usage?.tokens || 0;
       let turnUsageTokens = 0;
       try {
         const stream = subEngine.query({
@@ -461,9 +493,16 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
             // child is currently saying, not stale text from the prior
             // turn.
             agent.lastResult = capTail(assistantText, LAST_RESULT_MAX_CHARS);
+            agent.partial_output = agent.lastResult;
           }
           if (evt && evt.type === 'usage') {
-            turnUsageTokens += (evt.inputTokens || 0) + (evt.outputTokens || 0);
+            const cacheTokens = evt.cacheTokensAreIncludedInInput ? 0
+              : (evt.cacheReadTokens || 0) + (evt.cacheWriteTokens || 0);
+            turnUsageTokens += (evt.inputTokens || 0) + (evt.outputTokens || 0) + cacheTokens;
+            agent.usage.tokens = priorUsageTokens + turnUsageTokens;
+            if (agent.budget?.max_tokens && agent.usage.tokens >= agent.budget.max_tokens) {
+              stopForBudget(agent, `max_tokens (${agent.budget.max_tokens}) reached`);
+            }
           }
           if (evt && evt.type === 'error' && evt.error) {
             streamError = evt.error.message || String(evt.error);
@@ -475,10 +514,20 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
           }
         }
       } catch (err) {
-        transitionTerminal(agent, STATUS.FAILED, {
-          error: err && err.message ? err.message : String(err),
-          diagnostic: 'query_error',
-          deps,
+        if (!agent.budgetStopReason) {
+          transitionTerminal(agent, STATUS.FAILED, {
+            error: err && err.message ? err.message : String(err),
+            diagnostic: 'query_error',
+            deps,
+          });
+          return;
+        }
+      }
+
+      if (agent.budgetStopReason) {
+        agent.result = buildWallTimeBudgetResult(agent, agent.budgetStopReason);
+        transitionTerminal(agent, STATUS.COMPLETED, {
+          error: agent.budgetStopReason, diagnostic: 'execution_budget', deps,
         });
         return;
       }
@@ -527,6 +576,8 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
         if (typeof tickAgent === 'function') {
           const textTokenDelta = Math.max(0, (agent.liveness?.tokenCount || 0) - turnTokenStart);
           const tokenDelta = turnUsageTokens > 0 ? turnUsageTokens : textTokenDelta;
+          // Usage events are exposed live; tickAgent adds the turn delta once.
+          agent.usage.tokens = priorUsageTokens;
           tickResult = tickAgent(agent.id, {
             turns: 1,
             tokens: tokenDelta,
@@ -612,14 +663,15 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
   };
   try { agent.outputLog?.write(evt); } catch { /* ignore */ }
   if (agent.taskId && deps?.taskManager && agent.parentSessionId) {
-    const taskStatus = status === STATUS.COMPLETED ? 'succeeded'
+    const budgetExceeded = agent.result?.status === 'budget_exceeded';
+    const taskStatus = budgetExceeded ? 'failed' : status === STATUS.COMPLETED ? 'succeeded'
       : status === STATUS.CLOSED ? 'cancelled'
         : 'failed';
     try {
       deps.taskManager.completeTask(agent.parentSessionId, agent.taskId, {
         status: taskStatus,
-        error: error || agent.error || null,
-        summary: status === STATUS.COMPLETED
+        error: budgetExceeded ? agent.result.reason : (error || agent.error || null),
+        summary: budgetExceeded ? JSON.stringify(agent.result) : status === STATUS.COMPLETED
           ? (typeof agent.result === 'string' ? agent.result : (agent.lastResult || null))
           : null,
       });

package/yeaft/sub-agent/spawned-prompt.js

@@ -25,8 +25,20 @@
  * @param {'en'|'zh'} [args.language='en']
  * @returns {string} preamble block (already ## headed, ready to concat)
  */
-export function buildSpawnedPreamble({ parentName, parentVpId, agentName, mission, language = 'en' } = {}) {
-  const m = (mission || '').trim();
+export function buildSpawnedPreamble({ parentName, parentVpId, agentName, mission, expectedOutput, presetPrompt, budget, language = 'en' } = {}) {
+  // Resolve template markers before embedding: the outer VP renderer treats
+  // markers as sections of the whole soul and would drop the parent + contract.
+  const locale = language === 'zh' || language === 'zh-CN' ? 'zh' : 'en';
+  const sections = [...(presetPrompt || '').matchAll(/<!-- lang:(\w+) -->([\s\S]*?)(?=<!-- lang:|$)/g)];
+  const rolePrompt = sections.length
+    ? (sections.find(section => section[1] === locale) || sections.find(section => section[1] === 'en'))?.[2]?.trim()
+    : presetPrompt;
+  const contract = [
+    rolePrompt || '',
+    expectedOutput ? `## expected_output\nReturn the requested structure; mark unverified facts and blockers honestly.\n${JSON.stringify(expectedOutput)}` : '',
+    budget ? `## Execution budget\n${JSON.stringify(budget)}\nLimits are ceilings, not targets. Stop once the mission is answered. Return partial findings before exhausting the budget; do not automatically restart the same work.` : '',
+  ].filter(Boolean).join('\n\n');
+  const m = [(mission || '').trim(), contract].filter(Boolean).join('\n\n');
   if (language === 'zh') {
     const lines = [
       '## 你是 sub-agent',
@@ -40,7 +52,9 @@ export function buildSpawnedPreamble({ parentName, parentVpId, agentName, missio
       '## 行为约束',
       '- 不要再 spawn sub-agent（你已经没有 SpawnAgent / PromptAgent / WaitAgent / CloseAgent 工具）。',
       '- 不要 route_forward 给别的 VP，不要 ask_user。',
-      '- 完成时直接以 markdown 自由文本回复（end_turn）。建议结构："## 结果" / "## 关键发现" / "## 遗留问题"。',
+      '- 每次调用必须解决一个仍未解决的问题；先检查最小定向结果，再决定是否扩展。不要重复成功读取的范围、同义搜索或仅为轮询而调用工具。',
+      '- 不要把子任务扩展成全项目审计；证据已足够回答时立即收敛。工具活动不等于任务进展。',
+      '- 完成时遵守 expected_output；未指定则返回结果、关键证据、实际验证及遗留问题。不要用计划或过程评论冒充最终结果。',
       '- 失败/不可行也要明确说出来，不要假装完成。父 VP 会读你的最终消息。',
     ];
     return lines.join('\n');
@@ -57,7 +71,9 @@ export function buildSpawnedPreamble({ parentName, parentVpId, agentName, missio
     '## Constraints',
     '- Do NOT spawn further sub-agents (SpawnAgent / PromptAgent / WaitAgent / CloseAgent are not in your toolset).',
     '- Do NOT use route_forward to other VPs. Do NOT ask_user.',
-    '- When done, reply in free markdown (end_turn). Suggested structure: "## Result" / "## Key findings" / "## Open questions".',
+    '- Each call must resolve a remaining unknown. Inspect the smallest targeted result before expanding; do not repeat successful read ranges, equivalent searches, or poll tools without a concrete need.',
+    '- Do not expand the mission into a whole-project audit. Stop once sufficient evidence answers the mission. Tool activity is not evidence of progress.',
+    '- When done, follow expected_output if supplied; otherwise return result, key evidence, actual verification, and open questions. Plans and progress commentary are not final deliverables.',
     '- If the mission is infeasible or you fail, say so plainly. The parent will read your final message.',
   ];
   return lines.join('\n');

package/yeaft/tools/agent.js

@@ -24,6 +24,7 @@ import { defineTool } from './types.js';
 import { randomUUID } from 'crypto';
 import { getPersona, listPersonaIds } from '../personas.js';
 import { startSubAgent } from '../sub-agent/runner.js';
+import { resolveSubAgentBudget } from '../sub-agent/execution-control.js';
 import { STATUS, isTerminalAgentStatus } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness, makeLiveness } from '../sub-agent/liveness.js';
 import { TASK_RESULT_DELIVERY } from '../tasks/store.js';
@@ -89,11 +90,12 @@ export function validateSpec(input) {
     return { ok: false, error: 'spec must be an object' };
   }
   const { name, task, mission, expected_output, persona, budget } = input;
-  if (!name || typeof name !== 'string') {
+  if (!cleanString(name)) {
     return { ok: false, error: 'name is required' };
   }
-  if (!task && !mission) {
-    return { ok: false, error: 'task or mission is required' };
+  if ([task, mission].some(value => value !== undefined && !cleanString(value))
+      || (!cleanString(task) && !cleanString(mission))) {
+    return { ok: false, error: 'task or mission must be a non-empty string' };
   }
   if (persona && !getPersona(persona)) {
     return {
@@ -108,9 +110,10 @@ export function validateSpec(input) {
     if (typeof budget !== 'object' || budget === null) {
       return { ok: false, error: 'budget must be an object' };
     }
-    for (const k of ['max_tokens', 'max_turns', 'wall_time_ms']) {
-      if (budget[k] !== undefined && (typeof budget[k] !== 'number' || budget[k] <= 0)) {
-        return { ok: false, error: `budget.${k} must be a positive number` };
+    for (const k of ['max_tokens', 'max_turns', 'wall_time_ms', 'max_tool_calls']) {
+      if (budget[k] !== undefined && (!Number.isFinite(budget[k]) || budget[k] <= 0
+          || (['max_turns', 'max_tool_calls'].includes(k) && !Number.isSafeInteger(budget[k])))) {
+        return { ok: false, error: `budget.${k} must be finite and positive (counts must be integers)` };
       }
     }
   }
@@ -122,7 +125,7 @@ export function validateSpec(input) {
       task: task || mission,
       expected_output: expected_output || null,
       persona: persona || null,
-      budget: budget || null,
+      budget: resolveSubAgentBudget(budget, persona),
     },
   };
 }
@@ -221,8 +224,9 @@ export default defineTool({
     en: `Create a sub-agent to work on an independent task in parallel.
 
 Sub-agents run in their own context and can be given a concrete mission
-with an optional expected_output schema. Optional budget limits
-(max_tokens/max_turns/wall_time_ms) act as safety cutoffs only when supplied.
+with an optional expected_output schema. Default safety ceilings: 64 actual tool
+executions (128 for implementer) and 15 minutes; budget overrides each field.
+max_tokens is checked during provider usage; max_turns counts query turns, not tools.
 Pick a preset persona to pre-wire a tool subset and model tier:
   - explorer   : fast, read-only scout (Read/Grep/Glob/ListDir)
   - implementer: builder with full work tools (primary model)
@@ -232,7 +236,8 @@ Pick a preset persona to pre-wire a tool subset and model tier:
 Guidelines:
 - Give a clear, focused mission — what "done" looks like
 - Use expected_output when the return shape matters
-- Add a budget only when you need an explicit safety cutoff
+- Delegate only a bounded independent result; do simple work directly. Set scope, evidence and stopping conditions in mission.
+- Inspect execution counters and partial evidence before extending budgets; do not respawn the same exhausted mission automatically.
 
 Async orchestration:
   1. SpawnAgent  — starts the sub-agent as a background task and returns immediately.
@@ -251,7 +256,8 @@ workflow; use bounded WaitAgent calls and inspect liveness instead of blind loop
     zh: `创建一个子 Agent 并行处理独立任务。
 
 子 Agent 在独立上下文中运行，可给定具体 mission 和可选的 expected_output schema。
-可选的预算限制（max_tokens/max_turns/wall_time_ms）仅在设置后作为安全截止。
+默认安全上限：64 次实际工具执行（implementer 为 128 次）、15 分钟；budget 可逐项覆盖。
+max_tokens 在 provider usage 到达时检查；max_turns 是 query turn 数，不是工具调用数。
 选择预设 persona 来预配置工具子集和模型层级：
   - explorer   : 快速只读侦察（Read/Grep/Glob/ListDir）
   - implementer: 具备完整工作工具的构建者（主模型）
@@ -261,7 +267,8 @@ workflow; use bounded WaitAgent calls and inspect liveness instead of blind loop
 使用指南：
 - 给出清晰聚焦的 mission——"完成"是什么样子
 - 当返回结构重要时使用 expected_output
-- 仅在需要明确安全截止时添加 budget
+- 只委派有界且独立的结果；简单工作直接做。在 mission 中写清范围、证据和停止条件。
+- 扩大预算前检查实际执行计数和已有证据；不要自动重启同一个耗尽预算的任务。
 
 异步编排流程：
   1. SpawnAgent  — 启动子 Agent 作为后台任务并立即返回。
@@ -325,15 +332,19 @@ liveness，不要盲目循环。`
           max_turns: { type: 'number', description: {
           en: 'Optional turn ceiling; no default limit is applied',
           zh: '可选 turn 上限；默认不设限制',
+        } },
+          max_tool_calls: { type: 'integer', minimum: 1, description: {
+          en: 'Actual tool execution ceiling; default 64, or 128 for implementer. Includes parallel and discovered tools.',
+          zh: '实际工具执行上限；默认 64，implementer 为 128；包括并行及发现的工具。',
         } },
           wall_time_ms: { type: 'number', description: {
-          en: 'Optional elapsed-time ceiling in milliseconds; no default limit is applied',
-          zh: '可选耗时上限（毫秒）；默认不设限制',
+          en: 'Elapsed-time ceiling in milliseconds; default 900000 (15 minutes)',
+          zh: '耗时上限（毫秒）；默认 900000（15 分钟）',
         } },
         },
         description: {
-          en: 'Optional safety limits; no max_tokens/max_turns/wall_time_ms defaults are applied. Exceeding an explicit limit returns { status: "budget_exceeded", partial_output, reason }',
-          zh: '可选安全限制；默认不限制 max_tokens/max_turns/wall_time_ms。超过显式限制会返回 { status: "budget_exceeded", partial_output, reason }',
+          en: 'Override default tool/time safety ceilings; token/turn limits are optional. A cutoff returns { status: "budget_exceeded", partial_output, reason }, not successful completion.',
+          zh: '覆盖默认工具/时间安全上限；token/turn 限制可选。截止时返回 { status: "budget_exceeded", partial_output, reason }，不代表任务成功。',
         },
       },
       cwd: {