minimal-agent 0.18.7 → 0.18.9

package/src/memory/fileStore.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from 'node:crypto';
-import lockfile from 'proper-lockfile';
 import {
   chmod,
   mkdir,
@@ -10,14 +9,12 @@ import {
   stat,
 } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 
 import { agentStateDir } from '../context/agentHome.js';
 import { CATEGORY_DIR, MEMORY_ID_PATTERN } from './constants.js';
 import type { MemoryRecord, MemoryScope } from './types.js';
 
-const LOCK_STALE_MS = 120_000;
-const LOCK_WAIT_MS = 15_000;
 let mutationQueue: Promise<void> = Promise.resolve();
 
 export function memoryRootDir(): string {
@@ -84,28 +81,7 @@ export async function acquireFileLock(
 ): Promise<() => Promise<void>> {
   signal?.throwIfAborted();
   await ensurePrivateDir(dirname(path));
-  const deadline = Date.now() + LOCK_WAIT_MS;
-  while (true) {
-    signal?.throwIfAborted();
-    try {
-      // Do not steal old-version file locks. Restart old hosts before upgrading;
-      // their locks must be reviewed rather than aged out under a live writer.
-      const legacy = await stat(`${path}.lock`).catch(error => {
-        if (error.code === 'ENOENT') return null;
-        throw error;
-      });
-      if (legacy?.isFile()) throw new Error('MEMORY_LEGACY_LOCK：请停止旧版本宿主并检查遗留记忆锁');
-      const release = await lockfile.lock(path, {
-        realpath: false, retries: 0, stale: LOCK_STALE_MS, update: 10_000,
-      });
-      if (signal?.aborted) { await release(); signal.throwIfAborted(); }
-      return release;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ELOCKED') throw error;
-      if (Date.now() >= deadline) throw new Error('等待记忆文件锁超时');
-      await delay(40, undefined, { signal });
-    }
-  }
+  return acquireStateFileLock(path, { signal, label: 'MEMORY' });
 }
 
 export async function atomicWriteFile(

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,6 +1,8 @@
 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';
 export function capabilitiesForTools(tools) {
     const result = new Set();
     for (const tool of tools) {
@@ -194,15 +196,10 @@ const CAPABILITY_POLICIES = [
     },
     {
         id: 'execution.desktop-diagrams', layer: 'execution', profiles: ALL_PROFILES, source: 'native',
-        render: ({ surface, toolNames }) => [
-            '- 按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。',
-            surface === 'desktop'
-                ? '- Desktop/Web 聊天支持 mermaid 和 svg 围栏，不用裸 HTML。'
-                : surface === 'cli' || surface === 'tui'
-                    ? '- CLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。'
-                    : '- 跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。',
+        render: ({ surface, output, toolNames }) => [
+            visualPresentation(output ?? surface),
             toolNames.has('Skill') || toolNames.has('Read')
-                ? '- 加载可用的 dynamic-ui。'
+                ? '- 配图前加载可用的 dynamic-ui。'
                 : '',
         ].filter(Boolean).join('\n'),
     },
@@ -264,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',
@@ -299,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,11 +1,14 @@
 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,
   type CapabilityId,
 } from '../tools/capabilities.js';
 import { skillInvokeInstruction } from './skillList.js';
+import { visualPresentation } from './visualPresentation.js';
+import type { OutputContract } from '../runtime/outputContract.js';
 
 export type PromptPolicyLayer =
   | 'authority'
@@ -31,6 +34,7 @@ export type { CapabilityId } from '../tools/capabilities.js';
 export interface StablePromptContext {
   profile: AgentProfile;
   surface: AgentSurface;
+  output?: OutputContract;
   cwd: string;
   capabilities: ReadonlySet<CapabilityId>;
   toolNames: ReadonlySet<string>;
@@ -241,15 +245,10 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
   },
   {
     id: 'execution.desktop-diagrams', layer: 'execution', profiles: ALL_PROFILES, source: 'native',
-    render: ({ surface, toolNames }) => [
-      '- 按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。',
-      surface === 'desktop'
-        ? '- Desktop/Web 聊天支持 mermaid 和 svg 围栏，不用裸 HTML。'
-        : surface === 'cli' || surface === 'tui'
-          ? '- CLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。'
-          : '- 跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。',
+    render: ({ surface, output, toolNames }) => [
+      visualPresentation(output ?? surface),
       toolNames.has('Skill') || toolNames.has('Read')
-        ? '- 加载可用的 dynamic-ui。'
+        ? '- 配图前加载可用的 dynamic-ui。'
         : '',
     ].filter(Boolean).join('\n'),
   },
@@ -311,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',
@@ -343,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/prompts/promptAssembly.js

@@ -235,17 +235,24 @@ async function buildAdvisorTransient(profile, tools) {
         return '';
     return buildAdvisorStatusLine();
 }
-export async function assemblePromptEnvelope(options) {
-    const { cwd, tools, profile = 'main', includeProjectInstructions = true, includePlugins = profile === 'main', } = options;
-    const runtime = {
-        surface: profile === 'main' ? 'cli' : 'subagent',
+/** One default contract for stable, transient and combined prompt entry points.
+ * Preserve explicit legacy fields at this compatibility boundary; omission never
+ * grants memory, browser or vision capabilities.
+ */
+function resolvePromptRuntime(options) {
+    return {
+        surface: (options.profile ?? 'main') === 'main' ? 'cli' : 'subagent',
         conversationMode: 'private',
-        cwd,
+        cwd: options.cwd,
         interactiveAsk: true,
         supervisedBrowser: false,
         ownerLocalSession: false,
         ...options.runtime,
     };
+}
+export async function assemblePromptEnvelope(options) {
+    const { cwd, tools, profile = 'main', includeProjectInstructions = true, includePlugins = profile === 'main', } = options;
+    const runtime = resolvePromptRuntime(options);
     const { base, capabilities, stableContext } = await buildStableBase(cwd, tools, profile, runtime);
     const contextBundle = await buildTransientBundle(runtime, profile, tools, {
         includeProjectInstructions,
@@ -273,6 +280,7 @@ async function buildStableBase(cwd, tools, profile, runtime) {
     const stableContext = {
         profile,
         surface: runtime.surface,
+        output: runtime.output,
         cwd,
         capabilities,
         toolNames: new Set(tools.map((tool) => tool.name)),
@@ -289,19 +297,12 @@ async function buildStableBase(cwd, tools, profile, runtime) {
 /** Build only the cache-stable layer; performs no memory or project scans. */
 export async function assembleStablePrompt(options) {
     const profile = options.profile ?? 'main';
-    const runtime = {
-        surface: profile === 'main' ? 'cli' : 'subagent',
-        conversationMode: 'private',
-        cwd: options.cwd,
-        interactiveAsk: true,
-        supervisedBrowser: false,
-        ownerLocalSession: false,
-        ...options.runtime,
-    };
+    const runtime = resolvePromptRuntime(options);
     const key = [
         options.cwd,
         profile,
         runtime.surface,
+        JSON.stringify(runtime.output ?? null),
         runtime.conversationMode,
         createHash('sha256')
             .update(JSON.stringify(options.tools.map((tool) => ({
@@ -544,15 +545,7 @@ export async function buildTransientContext(options) {
 /** Structured counterpart used by the Harness for request-time budget reduction. */
 export async function buildTransientPromptBundle(options) {
     const profile = options.profile ?? 'main';
-    const runtime = {
-        surface: profile === 'main' ? 'cli' : 'subagent',
-        conversationMode: 'private',
-        cwd: options.cwd,
-        interactiveAsk: true,
-        supervisedBrowser: false,
-        ownerLocalSession: false,
-        ...options.runtime,
-    };
+    const runtime = resolvePromptRuntime(options);
     return buildTransientBundle(runtime, profile, options.tools, {
         includeProjectInstructions: options.includeProjectInstructions ?? true,
         includePlugins: options.includePlugins ?? profile === 'main',

package/src/prompts/promptAssembly.ts

@@ -88,6 +88,7 @@ const stablePromptCache = new Map<string, string>();
 import { normalizeBrowserRuntime } from '../runtime/browserRuntimeContext.js';
 
 export interface PromptRuntimeContext {
+  output?: import('../runtime/outputContract.js').OutputContract;
   surface: PromptSurface;
   host?: 'desktop' | 'tui' | 'cli' | 'stream-json' | 'workflow';
   conversationMode: import('../runtime/agentRuntimeContext.js').ConversationMode;
@@ -377,6 +378,22 @@ async function buildAdvisorTransient(
   return buildAdvisorStatusLine();
 }
 
+/** One default contract for stable, transient and combined prompt entry points.
+ * Preserve explicit legacy fields at this compatibility boundary; omission never
+ * grants memory, browser or vision capabilities.
+ */
+function resolvePromptRuntime(options: AssemblePromptOptions): PromptRuntimeContext {
+  return {
+    surface: (options.profile ?? 'main') === 'main' ? 'cli' : 'subagent',
+    conversationMode: 'private',
+    cwd: options.cwd,
+    interactiveAsk: true,
+    supervisedBrowser: false,
+    ownerLocalSession: false,
+    ...options.runtime,
+  };
+}
+
 export async function assemblePromptEnvelope(
   options: AssemblePromptOptions,
 ): Promise<PromptEnvelope> {
@@ -387,15 +404,7 @@ export async function assemblePromptEnvelope(
     includeProjectInstructions = true,
     includePlugins = profile === 'main',
   } = options;
-  const runtime: PromptRuntimeContext = {
-    surface: profile === 'main' ? 'cli' : 'subagent',
-    conversationMode: 'private',
-    cwd,
-    interactiveAsk: true,
-    supervisedBrowser: false,
-    ownerLocalSession: false,
-    ...options.runtime,
-  };
+  const runtime = resolvePromptRuntime(options);
 
   const { base, capabilities, stableContext } = await buildStableBase(
     cwd,
@@ -439,6 +448,7 @@ async function buildStableBase(
   const stableContext: StablePromptContext = {
     profile,
     surface: runtime.surface,
+    output: runtime.output,
     cwd,
     capabilities,
     toolNames: new Set(tools.map((tool) => tool.name)),
@@ -458,19 +468,12 @@ export async function assembleStablePrompt(
   options: AssemblePromptOptions,
 ): Promise<string> {
   const profile = options.profile ?? 'main';
-  const runtime: PromptRuntimeContext = {
-    surface: profile === 'main' ? 'cli' : 'subagent',
-    conversationMode: 'private',
-    cwd: options.cwd,
-    interactiveAsk: true,
-    supervisedBrowser: false,
-    ownerLocalSession: false,
-    ...options.runtime,
-  };
+  const runtime = resolvePromptRuntime(options);
   const key = [
     options.cwd,
     profile,
     runtime.surface,
+    JSON.stringify(runtime.output ?? null),
     runtime.conversationMode,
     createHash('sha256')
       .update(
@@ -784,15 +787,7 @@ export async function buildTransientPromptBundle(
   options: AssemblePromptOptions,
 ): Promise<ContextBundle> {
   const profile = options.profile ?? 'main';
-  const runtime: PromptRuntimeContext = {
-    surface: profile === 'main' ? 'cli' : 'subagent',
-    conversationMode: 'private',
-    cwd: options.cwd,
-    interactiveAsk: true,
-    supervisedBrowser: false,
-    ownerLocalSession: false,
-    ...options.runtime,
-  };
+  const runtime = resolvePromptRuntime(options);
   return buildTransientBundle(runtime, profile, options.tools, {
     includeProjectInstructions: options.includeProjectInstructions ?? true,
     includePlugins: options.includePlugins ?? profile === 'main',

package/src/prompts/visualPresentation.js

@@ -0,0 +1,28 @@
+import { resolveOutputContract } from '../runtime/outputContract.js';
+/** One output contract shared by preparation and tool-free publication. */
+export function visualPresentation(target) {
+    const output = typeof target === 'string' ? resolveOutputContract(target) : target;
+    const common = '按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。';
+    if (output.format === 'rich-markdown')
+        return `${common}\nDesktop/Web 聊天支持 ${output.diagrams.length ? output.diagrams.join(' 和 ') + ' 围栏' : 'Markdown，未声明图形渲染'}，不用裸 HTML。仅用已声明的图形格式替代字符框图；最终表达同样生效。${output.images ? '支持图片。' : ''}${output.attachments ? '附件须真实提交。' : ''}无法可靠画图则用文字/表格。`;
+    if (output.format === 'terminal')
+        return `${common}\nCLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。`;
+    if (output.format === 'structured')
+        return '仅按调用方结构化协议输出，不插入 Markdown 围栏或图形源码。';
+    return `${common}\n跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。`;
+}
+/** Conservative signal on PRIVATE candidates only, never a frontend converter.
+ * Require box borders in prose fences; ordinary code, trees and arrows are not diagrams.
+ */
+export function needsDiagramPreparation(candidate, request) {
+    const rejectsAscii = /(?:不要|不用|避免|别用|without|not|instead of)[^\n。！？]{0,24}(?:ascii|字符图|纯文本图)/i.test(request);
+    if (!rejectsAscii && /ascii|字符图|纯文本图|原样|不要.*(?:mermaid|svg)/i.test(request))
+        return false;
+    const fences = candidate.matchAll(/^(?:```|~~~)(?:text|plaintext)?[ \t]*\r?\n([\s\S]*?)^(?:```|~~~)[ \t]*$/gm);
+    for (const [, body] of fences) {
+        const borders = body.split('\n').filter(line => /[┌┐└┘┏┓┗┛+][─━\-]{3,}[┌┐└┘┏┓┗┛+]/.test(line));
+        if (borders.length >= 2 && /[│┃|].*\S.*[│┃|]/.test(body))
+            return true;
+    }
+    return false;
+}

package/src/prompts/visualPresentation.ts

@@ -0,0 +1,26 @@
+import type { AgentSurface } from '../runtime/agentRuntimeContext.js';
+import { resolveOutputContract, type OutputContract } from '../runtime/outputContract.js';
+
+/** One output contract shared by preparation and tool-free publication. */
+export function visualPresentation(target: AgentSurface | OutputContract): string {
+  const output = typeof target === 'string' ? resolveOutputContract(target) : target;
+  const common = '按需配图，优先 Mermaid/SVG；用户指定 ASCII、代码/目录树除外。';
+  if (output.format === 'rich-markdown') return `${common}\nDesktop/Web 聊天支持 ${output.diagrams.length ? output.diagrams.join(' 和 ') + ' 围栏' : 'Markdown，未声明图形渲染'}，不用裸 HTML。仅用已声明的图形格式替代字符框图；最终表达同样生效。${output.images ? '支持图片。' : ''}${output.attachments ? '附件须真实提交。' : ''}无法可靠画图则用文字/表格。`;
+  if (output.format === 'terminal') return `${common}\nCLI/TUI 直接回复用文字/表格/紧凑 ASCII，生成文件仍优先 Mermaid/SVG。`;
+  if (output.format === 'structured') return '仅按调用方结构化协议输出，不插入 Markdown 围栏或图形源码。';
+  return `${common}\n跟随最终阅读载体，不等同于终端：Web 用 mermaid/svg 围栏；保持协议契约，未知不假定可渲染。`;
+}
+
+/** Conservative signal on PRIVATE candidates only, never a frontend converter.
+ * Require box borders in prose fences; ordinary code, trees and arrows are not diagrams.
+ */
+export function needsDiagramPreparation(candidate: string, request: string): boolean {
+  const rejectsAscii = /(?:不要|不用|避免|别用|without|not|instead of)[^\n。！？]{0,24}(?:ascii|字符图|纯文本图)/i.test(request);
+  if (!rejectsAscii && /ascii|字符图|纯文本图|原样|不要.*(?:mermaid|svg)/i.test(request)) return false;
+  const fences = candidate.matchAll(/^(?:```|~~~)(?:text|plaintext)?[ \t]*\r?\n([\s\S]*?)^(?:```|~~~)[ \t]*$/gm);
+  for (const [, body] of fences) {
+    const borders = body!.split('\n').filter(line => /[┌┐└┘┏┓┗┛+][─━\-]{3,}[┌┐└┘┏┓┗┛+]/.test(line));
+    if (borders.length >= 2 && /[│┃|].*\S.*[│┃|]/.test(body!)) return true;
+  }
+  return false;
+}

package/src/runtime/agentRuntimeContext.js

@@ -1,3 +1,5 @@
+import { resolveOutputContract } from './outputContract.js';
+export { WEB_OUTPUT, resolveOutputContract } from './outputContract.js';
 import { isMemoryToolName } from '../tools/capabilities.js';
 import { normalizeBrowserRuntime } from './browserRuntimeContext.js';
 export function normalizeMemoryAccess(access) {
@@ -12,6 +14,7 @@ export function createAgentRuntimeContext(input) {
     const { browser: rawBrowser, ...rest } = input;
     return Object.freeze({
         ...rest,
+        output: resolveOutputContract(input.surface, input.output),
         ...(rawBrowser
             ? {
                 browser: normalizeBrowserRuntime(rawBrowser),