@yeaft/webchat-agent 1.0.568 → 1.0.569

package/yeaft/tools/registry.js

@@ -242,6 +242,35 @@ export function truncateToolResultIfNeeded(output, { toolName, language } = {})
   const originalBytes = Buffer.byteLength(text, 'utf8');
   if (originalBytes <= TOOL_RESULT_MAX_BYTES) return text;
 
+  // Preserve the error contract in the model projection; raw tool output
+  // remains available to tracing/persistence before this budget is applied.
+  if (toolName === 'Bash') {
+    const failure = parseToolErrorOutput(text);
+    if (failure && failure.code?.startsWith('bash_')) {
+      const projected = { ...failure, truncated: true, originalBytes };
+      for (const [key, value] of Object.entries(projected)) {
+        if (key !== 'output' && typeof value === 'string') projected[key] = truncateUtf8(value, 1024);
+      }
+      const source = typeof failure.output === 'string' ? failure.output : '';
+      const buffer = Buffer.from(source, 'utf8');
+      const sample = bytes => {
+        const half = Math.floor(bytes / 2);
+        let start = Math.max(0, buffer.length - half);
+        while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start += 1;
+        return truncateUtf8(source, half) + '\n[Middle omitted by tool result budget]\n' + buffer.subarray(start).toString('utf8');
+      };
+      let low = 0, high = Math.min(buffer.length, TOOL_RESULT_MAX_BYTES);
+      while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        projected.output = sample(mid);
+        if (Buffer.byteLength(JSON.stringify(projected), 'utf8') <= TOOL_RESULT_MAX_BYTES) low = mid;
+        else high = mid - 1;
+      }
+      projected.output = sample(low);
+      return JSON.stringify(projected);
+    }
+  }
+
   const markerFor = name => normalizeLanguage(language) === 'zh'
     ? `\n\n[已截断：${name} 返回 ${formatSize(originalBytes)}，上限为 ${formatSize(TOOL_RESULT_MAX_BYTES)}；原因：单个 tool result 超过 ${formatSize(TOOL_RESULT_MAX_BYTES)}，模型消息历史不会看到剩余内容]`
     : `\n\n[truncated: ${name} returned ${formatSize(originalBytes)}, capped at ${formatSize(TOOL_RESULT_MAX_BYTES)}; reason: single tool result exceeded ${formatSize(TOOL_RESULT_MAX_BYTES)}, the model message history will not see the rest]`;

package/yeaft/tools/update-agent.js

@@ -9,8 +9,8 @@ import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 export default defineTool({
   name: 'UpdateAgent',
   description: {
-    en: 'Adjust a live child in place after inspecting its progress: absolute lifetime time/tool/LLM budgets and explicit extra tool grants. Does not queue a prompt, reset usage, or revive a terminal/reporting child. Give evidence and the remaining task in reason; do not extend stalled or repeating work blindly. Bash permits arbitrary shell and writes, not a read-only sandbox; grant only necessary parent tools and isolate writable workspaces. Already dispatched work is not undone by revocation.',
-    zh: '检查进展后原地调整活跃子 Agent：累计时间/工具/LLM 上限及额外工具授权。不排队提示、不清零用量、不复活终止或收尾中的任务。reason 说明已有证据和剩余工作，勿盲目给停滞/重复任务扩额。Bash 可执行任意 Shell 和写入，并非只读沙箱；只授予必要的父级工具，写任务隔离 workspace。撤销不撤回已执行操作。',
+    en: 'Adjust a live child in place after inspecting its progress: absolute lifetime budgets, extra tool grants, or request a cooperative evidence-only final report. Finalization is control, not a prompt containing reason. Does not reset usage or revive a terminal/reporting child. Already dispatched work is not undone.',
+    zh: '检查进展后原地调整活跃子 Agent：累计预算、额外工具授权，或请求基于现有证据协作收尾。收尾是控制信号，不会把 reason 冒充提示词。不清零用量、不复活终止/报告中的任务，也不撤回已派发操作。',
   },
   parameters: {
     type: 'object',
@@ -32,6 +32,10 @@ export default defineTool({
         type: 'array', items: { type: 'string' }, maxItems: 32,
         description: { en: 'Replace extra persona grants with these canonical parent tool names (e.g. Bash, FileEdit); [] revokes extras, omission leaves grants unchanged', zh: '替换 persona 额外授权（如 Bash、FileEdit）；[] 撤销额外授权，省略则不变' },
       },
+      request_finalize: {
+        type: 'boolean',
+        description: { en: 'Request one tool-free final report from existing evidence, then end the child lifecycle normally', zh: '请求仅基于现有证据生成一次无工具最终报告，然后正常结束子任务生命周期' },
+      },
     },
     required: ['agent_id', 'reason'],
   },
@@ -42,10 +46,10 @@ export default defineTool({
     const fail = error => JSON.stringify({ error, next_steps: 'Inspect the current agent state and correct the request; do not respawn or repeat blindly.' });
     const agent = getAgentRegistry().get(input.agent_id);
     if (!agent || !agentBelongsToCaller(agent, ctx)) return fail(`Agent not found: ${input.agent_id}`);
-    if (isTerminalAgentStatus(agent.status) || agent.budgetReportStarted || agent.budgetStopReason
+    if (isTerminalAgentStatus(agent.status) || agent.budgetReportStarted || agent.finalizationRequested || agent.budgetStopReason
         || agent.abortController?.signal.aborted) return fail('Agent is terminal, stopping or already reporting; it cannot be extended');
     if (typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 2000) return fail('reason must contain 1..2000 characters of evidence and remaining work');
-    if (input.budget === undefined && input.allow_tools === undefined) return fail('budget or allow_tools is required');
+    if (input.budget === undefined && input.allow_tools === undefined && input.request_finalize !== true) return fail('budget, allow_tools, or request_finalize=true is required');
     if (input.budget !== undefined) {
       const error = validateBudget(input.budget);
       if (error) return fail(error);
@@ -58,6 +62,7 @@ export default defineTool({
     // All validation precedes mutation. Original usage/deadline origin are retained.
     agent.budget = { ...agent.budget, ...input.budget };
     if (grants) agent.allowTools = grants.tools;
+    if (input.request_finalize === true) agent.finalizationRequested = true;
     agent.controlRevision = (agent.controlRevision || 0) + 1;
     if (agent.execution && (agent.budget.max_tool_calls === undefined
         || agent.execution.toolCalls < agent.budget.max_tool_calls * 0.75)) agent.execution.warning = null;
@@ -68,6 +73,7 @@ export default defineTool({
     agent.refreshToolPolicy?.();
     agent.rearmWallTimeWatchdog?.();
     const event = { type: 'sub_agent_control_updated', at: Date.now(), reason: input.reason.trim(),
+      requestFinalize: input.request_finalize === true,
       previousBudget, budget: { ...agent.budget }, previousTools, allowTools: [...(agent.allowTools || [])] };
     agent.diagnostics ||= [];
     agent.diagnostics.push(event);
@@ -75,6 +81,9 @@ export default defineTool({
     try { agent.outputLog?.write(event); } catch { /* diagnostics must not fail the applied update */ }
     return JSON.stringify({ success: true, agentId: agent.id, status: agent.status,
       budget: agent.budget, allow_tools: agent.allowTools || [], liveness: diagnoseAgentLiveness(agent),
-      next_steps: 'Adjustment applied without restarting work. Continue the parent task; use PromptAgent only if new guidance is needed, then collect its reply. Revocation does not cancel already dispatched work.' });
+      finalizationRequested: agent.finalizationRequested === true,
+      next_steps: input.request_finalize === true
+        ? 'Cooperative wrap-up requested without turning reason into a child prompt. Use WaitAgent to collect the evidence-only final report; already dispatched work may finish first.'
+        : 'Adjustment applied without restarting work. Continue the parent task; use PromptAgent only if new guidance is needed, then collect its reply. Revocation does not cancel already dispatched work.' });
   },
 });

package/yeaft/tools/wait-agent.js

@@ -35,6 +35,7 @@ import { agentBelongsToCaller, getAgentRegistry } from './agent.js';
 import { isTerminalAgentStatus, STATUS } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
 import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
+import { describeAgentLifecycle, describeAgentOutcome } from '../sub-agent/outcome.js';
 
 /**
  * Build the status-specific next-step guidance the LLM reads after a wait.
@@ -55,6 +56,9 @@ function nextStepsFor(status, opts = {}) {
       'as an ordinary successful completion.'
     );
   }
+  if (opts.incomplete) {
+    return 'Sub-agent lifecycle ended with incomplete evidence. Inspect outcome and final_report; do not present partial verdict text as a completed review.';
+  }
   if (opts.timedOut && opts.stale) {
     return (
       'No observable event arrived within the diagnostic threshold. This does ' +
@@ -157,12 +161,15 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     next_steps: nextStepsFor(status, {
       timedOut,
       budgetExceeded: !!budgetResult,
+      incomplete: isTerminalAgentStatus(status) && !describeAgentOutcome(agent).complete,
       stale: liveness.stale,
       mustCollectReply: mustCollectReply && !liveness.stale,
     }),
     agentId: agent.id,
     name: agent.name,
     status,
+    lifecycle: describeAgentLifecycle(agent),
+    outcome: describeAgentOutcome(agent),
     error: agent.error || null,
     outputFile: agent.outputFile || null,
     liveness,
@@ -185,8 +192,17 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     env.budget_status = budgetResult.status;
     env.budget_reason = budgetResult.reason || null;
     env.partial_output = budgetResult.partial_output || '';
+    env.incomplete = true;
+    env.truncated = Boolean(budgetResult.truncated || budgetResult.final_report?.truncated);
+    env.final_report = budgetResult.final_report || null;
     env.budget_usage = budgetResult.usage || null;
   }
+  if (agent.finalizationRequested) {
+    env.incomplete = true;
+    env.final_report = agent.finalReport || null;
+    env.truncated = Boolean(agent.finalReport?.truncated);
+    env.partial_output = resultText;
+  }
   env.result = resultText;
   return env;
 }

package/yeaft/tools/wait-task.js

@@ -0,0 +1,73 @@
+/**
+ * wait-task.js — Bounded wait for one Session background task.
+ */
+
+import { defineTool } from './types.js';
+import { isTerminalTaskStatus } from '../tasks/store.js';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 600_000;
+
+export function taskWaitResult(result) {
+  if (!result?.ok) return { error: result?.error || 'Unable to wait for task' };
+  const task = result.task;
+  if (!task) return { error: 'Task state unavailable' };
+  const log = task.log && typeof task.log === 'object' ? task.log : {};
+  const taskResult = task.result && typeof task.result === 'object' ? task.result : {};
+  return {
+    taskId: task.id,
+    status: task.status,
+    terminal: isTerminalTaskStatus(task.status),
+    timedOut: result.timedOut === true,
+    exitCode: Number.isInteger(taskResult.exitCode) ? taskResult.exitCode : null,
+    signal: taskResult.signal || null,
+    resultDelivery: task.resultDelivery,
+    resultConsumed: false,
+    ...(task.runtime?.subAgentId ? { agentId: task.runtime.subAgentId } : {}),
+    ...(task.runtime?.cancelRequestedAt ? { cancelPending: !isTerminalTaskStatus(task.status) } : {}),
+    next_steps: 'Status only; no output was consumed. ReadTaskLog with your last read offset (or tail) for evidence; use WaitAgent for a child result. Do not use log.endOffset as an already-read cursor.',
+    error: taskResult.error || null,
+    log: {
+      ...(log.path ? { path: log.path } : {}),
+      bytes: Number.isFinite(log.bytes) ? log.bytes : 0,
+      endOffset: Number.isFinite(log.bytes) ? log.bytes : 0,
+    },
+  };
+}
+
+export default defineTool({
+  name: 'WaitTask',
+  description: {
+    en: 'Wait for one background task by taskId, up to a bounded timeout. Returns terminal status and a log cursor/reference, never the whole log. This does not cancel or retry the task.',
+    zh: '按 taskId 有界等待一个后台任务。仅返回终态和日志游标/引用，不返回完整日志；不会取消或重试任务。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId: { type: 'string', description: { en: 'Task id', zh: '任务 ID' } },
+      sessionId: { type: 'string', description: { en: 'Session id (defaults to current Session)', zh: 'Session ID（默认当前 Session）' } },
+      timeout_ms: { type: 'number', description: { en: `Wait timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})`, zh: `等待超时毫秒数（默认 ${DEFAULT_TIMEOUT_MS}，最大 ${MAX_TIMEOUT_MS}）` } },
+    },
+    required: ['taskId'],
+  },
+  timeoutMs: 0,
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
+  async execute(input = {}, ctx = {}) {
+    if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
+    if (ctx.sessionId && input.sessionId && input.sessionId !== ctx.sessionId) {
+      return JSON.stringify({ error: 'Task access is limited to the current Session', errorEffect: 'none' });
+    }
+    if (!input.taskId) return JSON.stringify({ error: 'taskId is required' });
+    const sessionId = input.sessionId || ctx.sessionId || 'default';
+    const timeoutMs = Math.min(Math.max(Number.isFinite(input.timeout_ms) ? input.timeout_ms : DEFAULT_TIMEOUT_MS, 0), MAX_TIMEOUT_MS);
+    const result = await ctx.taskManager.waitForTask(sessionId, input.taskId, {
+      timeoutMs,
+      signal: ctx.signal || null,
+      ownerVpId: ctx.currentVpId || null,
+    });
+    return JSON.stringify(taskWaitResult(result), null, 2);
+  },
+});