minimal-agent 0.18.8 → 0.18.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.8",
+  "version": "0.18.10",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/loop.js

@@ -50,6 +50,7 @@ import { assembleContextBundle, contextFragment, resizeContextBundle } from './c
 import { chat as defaultChat } from './llm/client.js';
 import { buildUserContent } from './multimodal.js';
 import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName, getToolGateDetails, } from './tools/index.js';
+import { createReadBudget } from './tools/shared/readBudget.js';
 import { configService } from './config/configService.js';
 import { capabilityForToolName } from './tools/capabilities.js';
 import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
@@ -69,6 +70,7 @@ import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
 import { stripThinkBlocks } from './utils/stripThink.js';
 import { orderedPool } from './runtime/orderedPool.js';
 import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
+import { delegationRuntimeGuidance } from './prompts/delegation.js';
 import { executionSegments } from './tools/executionSegments.js';
 import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
 const DELIVERY_ARTIFACT = '(?:文件|合同|协议|方案|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
@@ -239,6 +241,8 @@ export async function* runQuery(userInput, options) {
     let resultPresented = false;
     let presentedResultUnverified = false;
     let deliveryCorrectionAttempted = false;
+    let emptyResponseRecoveryAttempted = false;
+    let emptyResponseRecoveryReason = '';
     let askCorrectionAttempted = false;
     let diagramPreparationAttempted = false;
     const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
@@ -326,9 +330,13 @@ export async function* runQuery(userInput, options) {
         const parts = [
             transientFor(activeTools),
             coordinationText,
+            delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+                maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
+                maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
             diagramPreparationAttempted ? visualPresentation(output) : '',
             delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
             askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
+            emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
             deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
             advisorAvailable ? advisorCoordinator.transientReminder() : '',
             advisorAvailable
@@ -692,16 +700,25 @@ export async function* runQuery(userInput, options) {
                 requiredNames: [...effectiveToolSet.requiredNames],
             });
         advisorCoordinator.setAvailable(currentEffectiveToolSet.names.has('Advisor'));
+        // Tool availability may change during emergency fitting. Rebuild dynamic
+        // guidance against the actual request boundary, then account for its size.
+        requestTransientContext = buildRequestTransientContext();
+        lastRequestTransientContext = requestTransientContext;
+        const finalRequestBudget = buildContextBudgetPlan({
+            provider, history, tools: currentEffectiveToolSet.tools,
+            transientContext: requestTransientContext,
+        });
         if (emergencyFit.removedNames.length > 0) {
             yield {
                 type: 'warning',
                 message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
             };
         }
-        if (emergencyFit.plan.overBudget) {
+        toolCallContext.reserveReadChars = createReadBudget(finalRequestBudget.inputLimit - finalRequestBudget.totalInputTokens);
+        if (finalRequestBudget.overBudget) {
             yield {
                 type: 'error',
-                error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+                error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
                 code: 'context_overflow',
             };
             yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
@@ -999,8 +1016,19 @@ export async function* runQuery(userInput, options) {
                     yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
             }
             if (emptyResponse) {
-                // A no-tool response is already the model's terminal signal. Do not turn it
-                // into another model round, and do not persist/broadcast an empty bubble.
+                // Recover once within the existing turn budget, retaining tool receipts and
+                // advisor state. Never replay tools or expose an empty candidate as an answer.
+                if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
+                    emptyResponseRecoveryAttempted = true;
+                    emptyResponseRecoveryReason = lastFinishReason === 'length'
+                        ? '输出额度耗尽' : lastFinishReason === 'unknown'
+                        ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
+                    const message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
+                        id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+                    history.push(message);
+                    yield { type: 'injected_message', message };
+                    continue;
+                }
                 yield* retireDraft('empty_response');
             }
             else {
@@ -1162,7 +1190,9 @@ export async function* runQuery(userInput, options) {
                 trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
             };
             if (emptyResponse && !resultPresented) {
-                const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+                const warning = emptyResponseRecoveryAttempted
+                    ? '自动恢复后仍未生成最终答复，已有进展已保留。可以继续本轮或检查模型服务。'
+                    : '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
                 yield { type: 'warning', message: warning };
                 yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
             }

package/src/loop.ts

@@ -72,6 +72,7 @@ import {
   getToolGateDetails,
 } from './tools/index.js';
 import type { ToolGate } from './toolGate.js';
+import { createReadBudget } from './tools/shared/readBudget.js';
 import type {
   DeliverableManifest,
   ImageDetail,
@@ -113,6 +114,7 @@ import {
 import { stripThinkBlocks } from './utils/stripThink.js';
 import { orderedPool } from './runtime/orderedPool.js';
 import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
+import { delegationRuntimeGuidance } from './prompts/delegation.js';
 import { executionSegments } from './tools/executionSegments.js';
 import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
 
@@ -449,6 +451,8 @@ export async function* runQuery(
   let resultPresented = false;
   let presentedResultUnverified = false;
   let deliveryCorrectionAttempted = false;
+  let emptyResponseRecoveryAttempted = false;
+  let emptyResponseRecoveryReason = '';
   let askCorrectionAttempted = false;
   let diagramPreparationAttempted = false;
   const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
@@ -539,9 +543,13 @@ export async function* runQuery(
     const parts = [
       transientFor(activeTools),
       coordinationText,
+      delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+        maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
+        maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
       diagramPreparationAttempted ? visualPresentation(output) : '',
       delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
       askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
+      emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
       advisorAvailable ? advisorCoordinator.transientReminder() : '',
       advisorAvailable
@@ -917,16 +925,25 @@ export async function* runQuery(
     advisorCoordinator.setAvailable(
       currentEffectiveToolSet.names.has('Advisor'),
     );
+    // Tool availability may change during emergency fitting. Rebuild dynamic
+    // guidance against the actual request boundary, then account for its size.
+    requestTransientContext = buildRequestTransientContext();
+    lastRequestTransientContext = requestTransientContext;
+    const finalRequestBudget = buildContextBudgetPlan({
+      provider, history, tools: currentEffectiveToolSet.tools,
+      transientContext: requestTransientContext,
+    });
     if (emergencyFit.removedNames.length > 0) {
       yield {
         type: 'warning',
         message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
       };
     }
-    if (emergencyFit.plan.overBudget) {
+    toolCallContext.reserveReadChars = createReadBudget(finalRequestBudget.inputLimit - finalRequestBudget.totalInputTokens);
+    if (finalRequestBudget.overBudget) {
       yield {
         type: 'error',
-        error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+        error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
         code: 'context_overflow',
       };
       yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
@@ -1224,8 +1241,19 @@ export async function* runQuery(
         if (!deliveryCheckpoint.allow) yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
       }
       if (emptyResponse) {
-        // A no-tool response is already the model's terminal signal. Do not turn it
-        // into another model round, and do not persist/broadcast an empty bubble.
+        // Recover once within the existing turn budget, retaining tool receipts and
+        // advisor state. Never replay tools or expose an empty candidate as an answer.
+        if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
+          emptyResponseRecoveryAttempted = true;
+          emptyResponseRecoveryReason = lastFinishReason === 'length'
+            ? '输出额度耗尽' : lastFinishReason === 'unknown'
+              ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
+          const message: Message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
+            id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+          history.push(message);
+          yield { type: 'injected_message', message };
+          continue;
+        }
         yield* retireDraft('empty_response');
       } else {
         // Publication is a separate tool-free request. Nothing from preparation
@@ -1375,7 +1403,9 @@ export async function* runQuery(
         trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
       };
       if (emptyResponse && !resultPresented) {
-        const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+        const warning = emptyResponseRecoveryAttempted
+          ? '自动恢复后仍未生成最终答复，已有进展已保留。可以继续本轮或检查模型服务。'
+          : '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
         yield { type: 'warning', message: warning };
         yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
       } else if (pendingDelegations.length) {

package/src/memory/factLearning.js

@@ -2,7 +2,7 @@
  * its source material. A durable receipt makes retries idempotent. */
 import { readFile } from 'node:fs/promises';
 import { parseMemoryProposal } from './proposal.js';
-import { failureSchema, jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { failureSchema, jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { z } from 'zod';
@@ -437,7 +437,7 @@ export function scheduleFactLearning(options) {
     void runFactLearning(options)
         .catch((error) => {
         if (!options.signal?.aborted)
-            reportLearningFailure(directory(options.workspaceId));
+            recordBackgroundLearningFailure(options.workspaceId, 'facts', 'learning');
     })
         .finally(async () => {
         const settings = await memoryService.settings();
@@ -453,7 +453,7 @@ export function scheduleFactLearning(options) {
         if (pending.length)
             wakeAt(directory(options.workspaceId), Math.max(Date.now() + 1000, Math.min(...pending.map((turn) => turn.nextAttemptAt ?? Date.now()))), () => scheduleFactLearning({ ...options, force: false }), options.signal);
     })
-        .catch((error) => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+        .catch(() => recordBackgroundLearningFailure(options.workspaceId, 'facts', 'scheduling'));
 }
 export async function drainFactLearning() {
     await Promise.allSettled([...running.values()].map((task) => task.promise));

package/src/memory/factLearning.ts

@@ -2,7 +2,7 @@
  * its source material. A durable receipt makes retries idempotent. */
 import { readFile } from 'node:fs/promises';
 import { parseMemoryProposal } from './proposal.js';
-import { failureSchema, jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { failureSchema, jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { z } from 'zod';
@@ -574,7 +574,7 @@ export function scheduleFactLearning(
   void runFactLearning(options)
     .catch((error) => {
       if (!options.signal?.aborted)
-        reportLearningFailure(directory(options.workspaceId));
+        recordBackgroundLearningFailure(options.workspaceId, 'facts', 'learning');
     })
     .finally(async () => {
       const settings = await memoryService.settings();
@@ -604,11 +604,7 @@ export function scheduleFactLearning(
           options.signal,
         );
     })
-    .catch((error) =>
-      process.stderr.write(
-        `[minimal-agent memory] 恢复调度失败：${error.message}\n`,
-      ),
-    );
+    .catch(() => recordBackgroundLearningFailure(options.workspaceId, 'facts', 'scheduling'));
 }
 export async function drainFactLearning() {
   await Promise.allSettled([...running.values()].map((task) => task.promise));

package/src/memory/jobPolicy.js

@@ -13,23 +13,31 @@ export function recordJobFailure(job, error) {
         : /VERSION_CONFLICT|SOURCE_CHANGED/.test(message) ? 'conflict'
             : /timeout|超时|429|503|fetch|network|ECONN|连接/i.test(message) ? 'transient'
                 : 'unknown';
-    const consecutive = job.failure?.kind === kind ? job.failure.consecutive + 1 : 1;
+    // Changing failure categories is not recovery. Otherwise alternating provider
+    // and proposal failures can keep a source retrying forever.
+    const consecutive = (job.failure?.consecutive ?? 0) + 1;
     job.attempts = (job.attempts ?? 0) + 1;
-    job.failure = { kind, consecutive, paused: consecutive >= (kind === 'proposal' ? 3 : 6) };
+    job.failure = { kind, consecutive, paused: Boolean(job.failure?.paused) || consecutive >= (kind === 'proposal' ? 3 : 6) };
     job.nextAttemptAt = retryAt(consecutive);
 }
 export function jobEligible(job, force = false, now = Date.now()) {
     return force || (!job.failure?.paused && (job.nextAttemptAt ?? 0) <= now);
 }
-const notices = new Map();
-/** No raw provider response, quotes, or repeated terminal floods. Durable job
- * state retains the failure category and can be resumed with a forced run. */
-export function reportLearningFailure(key) {
-    const now = Date.now();
-    if (now - (notices.get(key) ?? 0) < 300_000)
-        return;
-    notices.set(key, now);
-    if (notices.size > 128)
-        notices.delete(notices.keys().next().value);
-    process.stderr.write('[minimal-agent memory] 后台学习未完成，资料已保留；可通过 MemoryMaintenance status 查看、run 重试。重复失败将暂停自动重试。\n');
+const health = new Map();
+/** Background services never write over a host's TUI. Durable queues retain
+ * source failures; this bounded process snapshot also exposes scheduler/IO errors
+ * that could not be persisted. No source text, paths or provider secrets. */
+export function recordBackgroundLearningFailure(workspaceId, partition, phase) {
+    const key = `${workspaceId}:${partition}`;
+    const previous = health.get(key);
+    health.delete(key);
+    health.set(key, { partition, phase, failures: (previous?.failures ?? 0) + 1, at: Date.now() });
+    if (health.size > 128)
+        health.delete(health.keys().next().value);
+}
+export function backgroundLearningHealth(workspaceId) {
+    return ['facts', 'experience'].flatMap(partition => {
+        const value = health.get(`${workspaceId}:${partition}`);
+        return value ? [{ ...value }] : [];
+    });
 }

package/src/memory/jobPolicy.ts

@@ -16,9 +16,11 @@ export function recordJobFailure(job: Job, error: unknown): void {
     : /VERSION_CONFLICT|SOURCE_CHANGED/.test(message) ? 'conflict'
     : /timeout|超时|429|503|fetch|network|ECONN|连接/i.test(message) ? 'transient'
     : 'unknown';
-  const consecutive = job.failure?.kind === kind ? job.failure.consecutive + 1 : 1;
+  // Changing failure categories is not recovery. Otherwise alternating provider
+  // and proposal failures can keep a source retrying forever.
+  const consecutive = (job.failure?.consecutive ?? 0) + 1;
   job.attempts = (job.attempts ?? 0) + 1;
-  job.failure = { kind, consecutive, paused: consecutive >= (kind === 'proposal' ? 3 : 6) };
+  job.failure = { kind, consecutive, paused: Boolean(job.failure?.paused) || consecutive >= (kind === 'proposal' ? 3 : 6) };
   job.nextAttemptAt = retryAt(consecutive);
 }
 
@@ -26,13 +28,22 @@ export function jobEligible(job: Job, force = false, now = Date.now()): boolean
   return force || (!job.failure?.paused && (job.nextAttemptAt ?? 0) <= now);
 }
 
-const notices = new Map<string, number>();
-/** No raw provider response, quotes, or repeated terminal floods. Durable job
- * state retains the failure category and can be resumed with a forced run. */
-export function reportLearningFailure(key: string): void {
-  const now = Date.now();
-  if (now - (notices.get(key) ?? 0) < 300_000) return;
-  notices.set(key, now);
-  if (notices.size > 128) notices.delete(notices.keys().next().value!);
-  process.stderr.write('[minimal-agent memory] 后台学习未完成，资料已保留；可通过 MemoryMaintenance status 查看、run 重试。重复失败将暂停自动重试。\n');
+type Partition = 'facts' | 'experience';
+type Health = { partition: Partition; phase: 'learning' | 'scheduling'; failures: number; at: number };
+const health = new Map<string, Health>();
+/** Background services never write over a host's TUI. Durable queues retain
+ * source failures; this bounded process snapshot also exposes scheduler/IO errors
+ * that could not be persisted. No source text, paths or provider secrets. */
+export function recordBackgroundLearningFailure(workspaceId: string, partition: Partition, phase: Health['phase']): void {
+  const key = `${workspaceId}:${partition}`;
+  const previous = health.get(key);
+  health.delete(key);
+  health.set(key, { partition, phase, failures: (previous?.failures ?? 0) + 1, at: Date.now() });
+  if (health.size > 128) health.delete(health.keys().next().value!);
+}
+export function backgroundLearningHealth(workspaceId: string): Health[] {
+  return (['facts', 'experience'] as const).flatMap(partition => {
+    const value = health.get(`${workspaceId}:${partition}`);
+    return value ? [{ ...value }] : [];
+  });
 }

package/src/memory/learning.js

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto';
 import { parseMemoryProposal } from './proposal.js';
 import { acquireModelSlot, MAX_MODEL_DURATION_MS } from './modelBudget.js';
-import { jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { ensurePrivateDir } from './fileStore.js';
@@ -343,7 +343,7 @@ export function scheduleMemoryMaintenance(options) {
     void runMemoryMaintenance(options).catch((error) => {
         if (options.signal?.aborted)
             return;
-        reportLearningFailure(experienceDirectory(options.workspaceId));
+        recordBackgroundLearningFailure(options.workspaceId, 'experience', 'learning');
     }).finally(async () => {
         const settings = await memoryService.settings();
         if (cancelled.has(experienceDirectory(options.workspaceId)) || options.signal?.aborted || !settings.autoRemember || !settings.learning?.enabled)
@@ -358,7 +358,7 @@ export function scheduleMemoryMaintenance(options) {
         if (cancelled.has(experienceDirectory(options.workspaceId)) || active.has(experienceDirectory(options.workspaceId)))
             return;
         wakeAt(experienceDirectory(options.workspaceId), Math.max(next, Date.now() + 1000), () => scheduleMemoryMaintenance({ ...options, force: false }), options.signal);
-    }).catch(error => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+    }).catch(() => recordBackgroundLearningFailure(options.workspaceId, 'experience', 'scheduling'));
 }
 /** Tests and orderly hosts may drain without polling or busy waiting. */
 export async function drainMemoryMaintenance() {

package/src/memory/learning.ts

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto';
 import { parseMemoryProposal } from './proposal.js';
 import { acquireModelSlot, MAX_MODEL_DURATION_MS } from './modelBudget.js';
-import { jobEligible, recordJobFailure, reportLearningFailure } from './jobPolicy.js';
+import { jobEligible, recordJobFailure, recordBackgroundLearningFailure } from './jobPolicy.js';
 import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { ensurePrivateDir } from './fileStore.js';
@@ -423,7 +423,7 @@ export function scheduleMemoryMaintenance(
   if (active.has(experienceDirectory(options.workspaceId))) return;
   void runMemoryMaintenance(options).catch((error) => {
     if (options.signal?.aborted) return;
-    reportLearningFailure(experienceDirectory(options.workspaceId));
+    recordBackgroundLearningFailure(options.workspaceId, 'experience', 'learning');
   }).finally(async () => {
     const settings = await memoryService.settings();
     if (cancelled.has(experienceDirectory(options.workspaceId)) || options.signal?.aborted || !settings.autoRemember || !settings.learning?.enabled) return;
@@ -436,7 +436,7 @@ export function scheduleMemoryMaintenance(
     // Cancellation can happen during the preceding disk reads.
     if (cancelled.has(experienceDirectory(options.workspaceId)) || active.has(experienceDirectory(options.workspaceId))) return;
     wakeAt(experienceDirectory(options.workspaceId), Math.max(next, Date.now() + 1000), () => scheduleMemoryMaintenance({ ...options, force: false }), options.signal);
-  }).catch(error => process.stderr.write(`[minimal-agent memory] 恢复调度失败：${error.message}\n`));
+  }).catch(() => recordBackgroundLearningFailure(options.workspaceId, 'experience', 'scheduling'));
 }
 
 /** Tests and orderly hosts may drain without polling or busy waiting. */

package/src/memory/learningModel.js

@@ -43,8 +43,10 @@ export function createLearningModel(provider, execute = chat) {
             }
         }
         signal.throwIfAborted();
-        if (!finished || !text.trim())
-            throw new Error('记忆整理模型未正常完成，保留待处理资料');
+        if (!finished)
+            throw new MemoryProposalError('format', '记忆整理模型未正常完成（截断或缺少正常结束标记），保留待处理资料');
+        if (!text.trim())
+            throw new MemoryProposalError('format', '记忆整理模型未正常完成（空正文），保留待处理资料');
         return { text, usage };
     };
 }

package/src/memory/learningModel.ts

@@ -49,8 +49,10 @@ export function createLearningModel(
       }
     }
     signal.throwIfAborted();
-    if (!finished || !text.trim())
-      throw new Error('记忆整理模型未正常完成，保留待处理资料');
+    if (!finished)
+      throw new MemoryProposalError('format', '记忆整理模型未正常完成（截断或缺少正常结束标记），保留待处理资料');
+    if (!text.trim())
+      throw new MemoryProposalError('format', '记忆整理模型未正常完成（空正文），保留待处理资料');
     return { text, usage };
   };
 }

package/src/prompts/delegation.js

@@ -0,0 +1,15 @@
+/** One delegation contract shared by the main prompt, tool discovery and runtime. */
+export const RESEARCH_DELEGATION_POLICY = `# 大范围阅读与并行调研
+- 先读项目说明、目录、入口与基线，建立问题地图，不先串行读完整仓库。批量阅读涉及多个独立模块、各需多轮探索时，优先同轮派发多个 Agent(agent_type="explore")；数量取决于独立工作量和宿主额度，不按文件数量机械切块。
+- 少量已知文件同轮批量读；强依赖调用链自行跟进。只读委派无需写入铺路或 worktree，不为获得 shell 升级 general。
+- 自包含任务书优先用 context.researchQuestions 写清问题、范围、停止条件，附基线、已知证据与排除项，不复制主历史。
+- 有独立工作时后台派发，否则同轮前台派发；不立即轮询或重复调查。整合证据、冲突与缺口；摘要不代表全文覆盖，并发不保证降低总 Token。`;
+export const AGENT_TOOL_DESCRIPTION = '启动隔离子任务（fork）并返回 agent_id。大型多模块批量阅读先定位入口，再优先同轮派发独立 explore 调查；少量已知文件直接批量读。explore 默认只读，general 使用 write_scopes 或 worktree。任务书自包含，context.researchQuestions 定义问题、范围、停止条件；AgentReport.findings 返回证据结论。run_in_background 立即返回供主 Agent 推进独立工作；resume_agent_id 续接子任务私有历史。reportMaxChars 限制预览，完整交接由 TaskOutput 获取。';
+export function delegationRuntimeGuidance(input) {
+    if (!input.available)
+        return '';
+    const remaining = Math.max(0, input.maxCalls - input.callsUsed);
+    if (!remaining)
+        return '本轮子任务派发次数已用完：收口已有子任务，其余调查由主 Agent 使用当前工具完成，不重复尝试派发。';
+    return `本轮可使用 Agent 进行隔离委派，剩余派发次数 ${remaining}，配置并发上限 ${Math.max(1, Math.min(8, input.maxConcurrent))}（实际槽位由调度器协调）。大型批量阅读先建立问题地图，再优先并行派发独立 explore 调查；不要把所有模块留在主上下文串行阅读。少量已知文件仍直接批量读。`;
+}

package/src/prompts/delegation.ts

@@ -0,0 +1,20 @@
+/** One delegation contract shared by the main prompt, tool discovery and runtime. */
+export const RESEARCH_DELEGATION_POLICY = `# 大范围阅读与并行调研
+- 先读项目说明、目录、入口与基线，建立问题地图，不先串行读完整仓库。批量阅读涉及多个独立模块、各需多轮探索时，优先同轮派发多个 Agent(agent_type="explore")；数量取决于独立工作量和宿主额度，不按文件数量机械切块。
+- 少量已知文件同轮批量读；强依赖调用链自行跟进。只读委派无需写入铺路或 worktree，不为获得 shell 升级 general。
+- 自包含任务书优先用 context.researchQuestions 写清问题、范围、停止条件，附基线、已知证据与排除项，不复制主历史。
+- 有独立工作时后台派发，否则同轮前台派发；不立即轮询或重复调查。整合证据、冲突与缺口；摘要不代表全文覆盖，并发不保证降低总 Token。`;
+
+export const AGENT_TOOL_DESCRIPTION = '启动隔离子任务（fork）并返回 agent_id。大型多模块批量阅读先定位入口，再优先同轮派发独立 explore 调查；少量已知文件直接批量读。explore 默认只读，general 使用 write_scopes 或 worktree。任务书自包含，context.researchQuestions 定义问题、范围、停止条件；AgentReport.findings 返回证据结论。run_in_background 立即返回供主 Agent 推进独立工作；resume_agent_id 续接子任务私有历史。reportMaxChars 限制预览，完整交接由 TaskOutput 获取。';
+
+export function delegationRuntimeGuidance(input: {
+  available: boolean;
+  maxConcurrent: number;
+  callsUsed: number;
+  maxCalls: number;
+}): string {
+  if (!input.available) return '';
+  const remaining = Math.max(0, input.maxCalls - input.callsUsed);
+  if (!remaining) return '本轮子任务派发次数已用完：收口已有子任务，其余调查由主 Agent 使用当前工具完成，不重复尝试派发。';
+  return `本轮可使用 Agent 进行隔离委派，剩余派发次数 ${remaining}，配置并发上限 ${Math.max(1, Math.min(8, input.maxConcurrent))}（实际槽位由调度器协调）。大型批量阅读先建立问题地图，再优先并行派发独立 explore 调查；不要把所有模块留在主上下文串行阅读。少量已知文件仍直接批量读。`;
+}

package/src/prompts/policyRegistry.js

@@ -1,4 +1,5 @@
 import { CODE_REVIEW_RUBRIC } from './codeReview.js';
+import { RESEARCH_DELEGATION_POLICY } from './delegation.js';
 import { capabilityForToolName, } from '../tools/capabilities.js';
 import { skillInvokeInstruction } from './skillList.js';
 import { visualPresentation } from './visualPresentation.js';
@@ -260,7 +261,7 @@ const CAPABILITY_POLICIES = [
     {
         id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
         requiresTools: ['Agent'],
-        render: () => '- 大范围调查先定位入口、模块边界与基线，不穷尽读取。独立且需多轮探索的问题可同轮派发 explore Agent，数量取决于独立工作量和宿主额度，不为并行而拆分；少量已知文件/网址直接批量读，强顺序或协调开销大于收益时自行完成。主 Agent 保留跨模块判断，有独立工作时后台派发并推进，不重复调查或立即轮询。任务书写清问题、范围、停止条件、排除项和已知证据，不复制私有历史。按问题整合结论与阅读证据，区分观察、推断、建议；冲突核验不投票，只补读关键结论、版本变化与修改位置。文件清单不代表全文覆盖。子任务用实际可用的搜索/正文工具，动态浏览器归主 Agent；不得为只读命令升级为 general。',
+        render: () => RESEARCH_DELEGATION_POLICY,
     },
     {
         id: 'capability.agent-handoff', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
@@ -295,7 +296,7 @@ const CAPABILITY_POLICIES = [
             if (toolNames.has('RecallMemory'))
                 rules.push('自包含任务无需检索记忆。依赖跨会话用户信息、偏好、决定或项目背景时，先检查已注入证据；缺少相关信息再用 RecallMemory，避免重复检索或直接反问用户。查询无关命中时停止扩大检索；旧结论与现场冲突时重新查证，未在本轮核验的历史结论标明来源及可能过时。');
             if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory'))
-                rules.push('纠正：RecallMemory 定位 → UpdateMemory(expectedVersion)；冲突回执充分则合并重试，否则重读。语义未变不重写。');
+                rules.push('RecallMemory 读版本 → UpdateMemory：update 原话/review 待复核/confirm 确认；冲突重读，拒绝不重试。');
             if (toolNames.has('ForgetMemory'))
                 rules.push('ForgetMemory 仅响应当前明确遗忘要求。');
             if (toolNames.has('ConfirmMemory'))

package/src/prompts/policyRegistry.ts

@@ -1,5 +1,6 @@
 import type { Tool } from '../types.js';
 import { CODE_REVIEW_RUBRIC } from './codeReview.js';
+import { RESEARCH_DELEGATION_POLICY } from './delegation.js';
 import type { AgentProfile, AgentSurface } from '../runtime/agentRuntimeContext.js';
 import {
   capabilityForToolName,
@@ -309,7 +310,7 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
   {
     id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
     requiresTools: ['Agent'],
-    render: () => '- 大范围调查先定位入口、模块边界与基线，不穷尽读取。独立且需多轮探索的问题可同轮派发 explore Agent，数量取决于独立工作量和宿主额度，不为并行而拆分；少量已知文件/网址直接批量读，强顺序或协调开销大于收益时自行完成。主 Agent 保留跨模块判断，有独立工作时后台派发并推进，不重复调查或立即轮询。任务书写清问题、范围、停止条件、排除项和已知证据，不复制私有历史。按问题整合结论与阅读证据，区分观察、推断、建议；冲突核验不投票，只补读关键结论、版本变化与修改位置。文件清单不代表全文覆盖。子任务用实际可用的搜索/正文工具，动态浏览器归主 Agent；不得为只读命令升级为 general。',
+    render: () => RESEARCH_DELEGATION_POLICY,
   },
   {
     id: 'capability.agent-handoff', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
@@ -341,7 +342,7 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
       ];
       if (toolNames.has('RememberMemory')) rules.push('RememberMemory 保存明确要求记住的新事实；后台提炼启用时普通陈述交后台处理，不重复写入。自动记忆关闭时仅响应明确保存要求；失败如实说明，不阻断任务。');
       if (toolNames.has('RecallMemory')) rules.push('自包含任务无需检索记忆。依赖跨会话用户信息、偏好、决定或项目背景时，先检查已注入证据；缺少相关信息再用 RecallMemory，避免重复检索或直接反问用户。查询无关命中时停止扩大检索；旧结论与现场冲突时重新查证，未在本轮核验的历史结论标明来源及可能过时。');
-      if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory')) rules.push('纠正：RecallMemory 定位 → UpdateMemory(expectedVersion)；冲突回执充分则合并重试，否则重读。语义未变不重写。');
+      if (toolNames.has('RecallMemory') && toolNames.has('UpdateMemory')) rules.push('RecallMemory 读版本 → UpdateMemory：update 原话/review 待复核/confirm 确认；冲突重读，拒绝不重试。');
       if (toolNames.has('ForgetMemory')) rules.push('ForgetMemory 仅响应当前明确遗忘要求。');
       if (toolNames.has('ConfirmMemory')) rules.push('用户重新确认相同事实时使用 ConfirmMemory 更新确认时间，不创建副本。');
       if (toolNames.has('ReviewMemories')) rules.push('已过复核周期的记录只降低优先级并提示复核，不自动删除。');

package/src/tools/agent/agent.js

@@ -25,6 +25,7 @@
  * ============================================================
  */
 import { randomUUID } from 'node:crypto';
+import { AGENT_TOOL_DESCRIPTION } from '../../prompts/delegation.js';
 import { researchQuestionSchema, researchPreview } from './research.js';
 import { EventEmitter } from 'node:events';
 import { access } from 'node:fs/promises';
@@ -106,7 +107,7 @@ const inputSchema = z.object({
 const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
-const description = 'Launch an isolated sub-agent with a self-contained prompt. Returns agent_id; run_in_background returns immediately, resume_agent_id resumes private history. explore is read-only; general uses write_scopes or an explicit worktree. context.researchQuestions defines question IDs, scope and stopping conditions; structured findings link conclusions to tool evidence. Full handoff and paged findings remain available through TaskOutput.';
+const description = AGENT_TOOL_DESCRIPTION;
 // ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
 /** 任务回传契约。能力与权限已经由 assembleBasePrompt profile 精确注入。 */
 const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）

package/src/tools/agent/agent.ts

@@ -26,6 +26,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { AGENT_TOOL_DESCRIPTION } from '../../prompts/delegation.js';
 import { researchQuestionSchema, researchPreview } from './research.js';
 import { EventEmitter } from 'node:events';
 import { access } from 'node:fs/promises';
@@ -152,7 +153,7 @@ const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
 
-const description = 'Launch an isolated sub-agent with a self-contained prompt. Returns agent_id; run_in_background returns immediately, resume_agent_id resumes private history. explore is read-only; general uses write_scopes or an explicit worktree. context.researchQuestions defines question IDs, scope and stopping conditions; structured findings link conclusions to tool evidence. Full handoff and paged findings remain available through TaskOutput.';
+const description = AGENT_TOOL_DESCRIPTION;
 
 // ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
 

package/src/tools/applypatch/applyPatch.js

@@ -341,7 +341,7 @@ async function call(input, context) {
                 contentHash: hashFileBytes(encodeTextFile(file.after, file.encoding)),
             }, context?.sessionState?.fileReads);
         emitFileMutation(file.path);
-        summaries.push(`${file.activity}: ${file.label} (+${patch.additions} -${patch.deletions})`);
+        summaries.push(`${file.activity}: ${file.label} (${patch.additions === undefined ? 'diff 未统计' : `+${patch.additions} -${patch.deletions}`})`);
     }
     return {
         ok: true,

package/src/tools/applypatch/applyPatch.ts

@@ -403,7 +403,7 @@ async function call(
       );
     emitFileMutation(file.path);
     summaries.push(
-      `${file.activity}: ${file.label} (+${patch.additions} -${patch.deletions})`,
+      `${file.activity}: ${file.label} (${patch.additions === undefined ? 'diff 未统计' : `+${patch.additions} -${patch.deletions}`})`,
     );
   }
   return {