minimal-agent 0.18.7 → 0.18.8

package/package.json

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

package/src/context/persistContext.js

@@ -91,7 +91,7 @@ export function filterEphemeralMessages(messages) {
 }
 /**
  * 保存当前 messages 为"上下文文件"，覆盖之前内容。
- * 写失败不抛——丢一次落盘比把进程崩掉划算。
+ * 自动保存默认尽力写入；显式用户操作使用 strict，在写失败时抛错。
  *
  * v2.x 新增：写盘前过滤掉 _ephemeral=true 的 system 消息（UI 临时提示，
  * 不应进入持久化历史）。
@@ -116,6 +116,10 @@ export async function saveContext(messages, file, options) {
         await rename(temp, target);
     }
     catch (e) {
+        // Explicit user mutations must not report success when persistence failed.
+        // Ordinary turn autosave retains its existing best-effort behavior.
+        if (options?.strict)
+            throw e;
         // 不抛（持久化失败不该影响对话本身），但要出声——磁盘满/权限问题时
         // 用户整段会话会静默丢失；与 clearContext 的 archive 失败处理风格对齐。
         try {

package/src/context/persistContext.ts

@@ -101,12 +101,12 @@ export function filterEphemeralMessages(messages: Message[]): Message[] {
 
 /**
  * 保存当前 messages 为"上下文文件"，覆盖之前内容。
- * 写失败不抛——丢一次落盘比把进程崩掉划算。
+ * 自动保存默认尽力写入；显式用户操作使用 strict，在写失败时抛错。
  *
  * v2.x 新增：写盘前过滤掉 _ephemeral=true 的 system 消息（UI 临时提示，
  * 不应进入持久化历史）。
  */
-export async function saveContext(messages: Message[], file?: string, options?: { replaceDisplayHistory?: boolean }): Promise<void> {
+export async function saveContext(messages: Message[], file?: string, options?: { replaceDisplayHistory?: boolean; strict?: boolean }): Promise<void> {
   const target = file ?? getContextPath();
   const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
   try {
@@ -122,6 +122,9 @@ export async function saveContext(messages: Message[], file?: string, options?:
     await writeFile(temp, JSON.stringify(data), { encoding: 'utf8', mode: 0o600 });
     await rename(temp, target);
   } catch (e) {
+    // Explicit user mutations must not report success when persistence failed.
+    // Ordinary turn autosave retains its existing best-effort behavior.
+    if (options?.strict) throw e;
     // 不抛（持久化失败不该影响对话本身），但要出声——磁盘满/权限问题时
     // 用户整段会话会静默丢失；与 clearContext 的 archive 失败处理风格对齐。
     try {

package/src/loop.js

@@ -29,6 +29,8 @@
 import crypto from 'node:crypto';
 import { answerPreparationNotice } from './runtime/answerPreparation.js';
 import { finalAnswerMessages } from './runtime/finalAnswer.js';
+import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
 import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
 import { conciseToolPath } from './runtime/toolDisplay.js';
 import { dirname, resolve } from 'node:path';
@@ -238,6 +240,8 @@ export async function* runQuery(userInput, options) {
     let presentedResultUnverified = false;
     let deliveryCorrectionAttempted = false;
     let askCorrectionAttempted = false;
+    let diagramPreparationAttempted = false;
+    const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
     const subagents = await configService.subagents();
     await hydrateSessionWorktree({
         sessionState,
@@ -246,6 +250,8 @@ export async function* runQuery(userInput, options) {
         cwd: runtimeContext.cwd,
     });
     const toolCallContext = {
+        output,
+        availableToolNames: () => currentEffectiveToolSet.names,
         executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
         history,
         sessionState,
@@ -320,6 +326,7 @@ export async function* runQuery(userInput, options) {
         const parts = [
             transientFor(activeTools),
             coordinationText,
+            diagramPreparationAttempted ? visualPresentation(output) : '',
             delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
             askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
             deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
@@ -737,7 +744,7 @@ export async function* runQuery(userInput, options) {
             for await (const ev of chatFn({
                 provider,
                 messages: modelMessages,
-                tools: currentEffectiveToolSet.tools,
+                tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'preparation'),
                 signal,
                 conversationMode: runtimeContext.conversationMode ?? 'private',
                 promptCache: options.promptCache,
@@ -896,6 +903,16 @@ export async function* runQuery(userInput, options) {
                 function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) } });
             assistantText = '';
         }
+        // Count the calls that survived review scheduling, including failed loads.
+        for (const call of toolCallsByIndex) {
+            if (call.function.name !== 'Skill')
+                continue;
+            try {
+                if (JSON.parse(call.function.arguments).name === 'dynamic-ui')
+                    diagramPreparationAttempted = true;
+            }
+            catch { /* Ordinary tool validation reports malformed arguments. */ }
+        }
         const assistantMsg = {
             role: 'assistant',
             content: assistantText.length > 0 ? assistantText : null,
@@ -909,6 +926,20 @@ export async function* runQuery(userInput, options) {
         };
         // 4. 没有工具调用 → 整轮交互结束
         finalResponse: if (toolCallsByIndex.length === 0) {
+            // Repair only private preparation, through the ordinary tool pipeline.
+            // One attempt per turn, including missing/failed skills; never rewind a reply.
+            if (!diagramPreparationAttempted && !options.responseFormat
+                && runtimeContext.profile === 'main' && output.diagrams.length > 0
+                && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
+                && needsDiagramPreparation(assistantText, userInput)) {
+                diagramPreparationAttempted = true;
+                toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+                        name: 'Skill', arguments: JSON.stringify({ name: 'dynamic-ui' }),
+                    } });
+                assistantMsg.content = null;
+                assistantMsg.tool_calls = toolCallsByIndex;
+                break finalResponse;
+            }
             if (!askCorrectionAttempted && runtimeContext.interactiveAsk
                 && currentEffectiveToolSet.names.has('AskUserQuestion')
                 && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
@@ -979,14 +1010,14 @@ export async function* runQuery(userInput, options) {
                 let publicationInterrupted = false;
                 let streamed = false;
                 if (!options.responseFormat && runtimeContext.profile === 'main'
-                    && (runtimeContext.surface === 'desktop' || runtimeContext.surface === 'tui')) {
+                    && output.finalDelivery === 'stream') {
                     const candidate = assistantText;
                     const candidateFinishReason = lastFinishReason;
                     let publishedText = '';
                     let publicationDone = false;
                     yield { type: 'stage_change', stage: 'streaming' };
                     try {
-                        const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText);
+                        const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText, output);
                         const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
                         if (publicationPlan.overBudget)
                             throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
@@ -998,7 +1029,7 @@ export async function* runQuery(userInput, options) {
                         for await (const event of chatFn({
                             provider,
                             messages: publicationMessages,
-                            tools: [], signal,
+                            tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), signal,
                             conversationMode: runtimeContext.conversationMode ?? 'private',
                             promptCache: options.promptCache,
                         })) {
@@ -1015,11 +1046,8 @@ export async function* runQuery(userInput, options) {
                                 break;
                             }
                             if (event.type === 'text_delta') {
-                                // Never expose a rewrite of the reviewed candidate. Previously
-                                // published chunks are necessarily an exact prefix of it.
-                                if (!candidate.startsWith(publishedText + event.delta)) {
-                                    throw new Error('发布内容偏离定稿，使用原定稿。');
-                                }
+                                // Final expression is live generation, not an exact-copy replay.
+                                // Once visible, text is never replaced or joined with a different draft.
                                 publishedText += event.delta;
                                 streamed = true;
                                 yield { type: 'text', delta: event.delta };
@@ -1040,26 +1068,20 @@ export async function* runQuery(userInput, options) {
                             throw new Error('最终答案流缺少有效的结束状态。');
                         if (!publishedText.trim() && !publicationInterrupted)
                             throw new Error('最终表达未返回正文。');
-                        if (!publicationInterrupted && publishedText !== candidate)
-                            throw new Error('最终表达未完整传递定稿。');
                     }
                     catch (error) {
                         publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || error?.name === 'AbortError';
                         publicationError = error;
                     }
-                    if (publicationError && !publicationInterrupted) {
-                        yield { type: 'warning', message: '流式发布未完成，已使用原定稿补齐；未重新生成或改写答案。' };
-                        const remaining = candidate.slice(publishedText.length);
-                        if (remaining) {
-                            yield { type: 'text', delta: remaining };
-                            streamed = true;
-                        }
+                    if (publicationError && !publicationInterrupted && !publishedText) {
+                        yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
+                        yield { type: 'text', delta: candidate };
+                        streamed = true;
                         publishedText = candidate;
+                        lastFinishReason = candidateFinishReason;
                         publicationError = undefined;
                     }
                     assistantText = publishedText;
-                    if (!publicationInterrupted)
-                        lastFinishReason = candidateFinishReason;
                     assistantMsg.content = publishedText || null;
                     if (!publishedText) {
                         if (publicationInterrupted)

package/src/loop.ts

@@ -30,6 +30,8 @@
 import crypto from 'node:crypto';
 import { answerPreparationNotice } from './runtime/answerPreparation.js';
 import { finalAnswerMessages } from './runtime/finalAnswer.js';
+import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
 import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
 import { conciseToolPath } from './runtime/toolDisplay.js';
 import { dirname, resolve } from 'node:path';
@@ -448,6 +450,8 @@ export async function* runQuery(
   let presentedResultUnverified = false;
   let deliveryCorrectionAttempted = false;
   let askCorrectionAttempted = false;
+  let diagramPreparationAttempted = false;
+  const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
   const subagents = await configService.subagents();
   await hydrateSessionWorktree({
     sessionState,
@@ -456,6 +460,8 @@ export async function* runQuery(
     cwd: runtimeContext.cwd,
   });
   const toolCallContext: ToolCallContext = {
+    output,
+    availableToolNames: () => currentEffectiveToolSet.names,
     executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
     history,
     sessionState,
@@ -533,6 +539,7 @@ export async function* runQuery(
     const parts = [
       transientFor(activeTools),
       coordinationText,
+      diagramPreparationAttempted ? visualPresentation(output) : '',
       delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
       askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
@@ -966,7 +973,7 @@ export async function* runQuery(
       for await (const ev of chatFn({
         provider,
         messages: modelMessages,
-        tools: currentEffectiveToolSet.tools,
+        tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'preparation'),
         signal,
         conversationMode: runtimeContext.conversationMode ?? 'private',
         promptCache: options.promptCache,
@@ -1124,6 +1131,13 @@ export async function* runQuery(
         function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) } });
       assistantText = '';
     }
+    // Count the calls that survived review scheduling, including failed loads.
+    for (const call of toolCallsByIndex) {
+      if (call.function.name !== 'Skill') continue;
+      try {
+        if (JSON.parse(call.function.arguments).name === 'dynamic-ui') diagramPreparationAttempted = true;
+      } catch { /* Ordinary tool validation reports malformed arguments. */ }
+    }
     const assistantMsg: Message = {
       role: 'assistant',
       content: assistantText.length > 0 ? assistantText : null,
@@ -1137,6 +1151,20 @@ export async function* runQuery(
     };
     // 4. 没有工具调用 → 整轮交互结束
     finalResponse: if (toolCallsByIndex.length === 0) {
+      // Repair only private preparation, through the ordinary tool pipeline.
+      // One attempt per turn, including missing/failed skills; never rewind a reply.
+      if (!diagramPreparationAttempted && !options.responseFormat
+        && runtimeContext.profile === 'main' && output.diagrams.length > 0
+        && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
+        && needsDiagramPreparation(assistantText, userInput)) {
+        diagramPreparationAttempted = true;
+        toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+          name: 'Skill', arguments: JSON.stringify({ name: 'dynamic-ui' }),
+        } });
+        assistantMsg.content = null;
+        assistantMsg.tool_calls = toolCallsByIndex;
+        break finalResponse;
+      }
       if (!askCorrectionAttempted && runtimeContext.interactiveAsk
         && currentEffectiveToolSet.names.has('AskUserQuestion')
         && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
@@ -1206,14 +1234,14 @@ export async function* runQuery(
         let publicationInterrupted = false;
         let streamed = false;
         if (!options.responseFormat && runtimeContext.profile === 'main'
-          && (runtimeContext.surface === 'desktop' || runtimeContext.surface === 'tui')) {
+          && output.finalDelivery === 'stream') {
           const candidate = assistantText;
           const candidateFinishReason = lastFinishReason;
           let publishedText = '';
           let publicationDone = false;
           yield { type: 'stage_change', stage: 'streaming' };
           try {
-            const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText);
+            const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText, output);
             const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
             if (publicationPlan.overBudget) throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
             if (signal?.aborted || options.hasQueuedInput?.()) {
@@ -1224,7 +1252,7 @@ export async function* runQuery(
             for await (const event of chatFn({
               provider,
               messages: publicationMessages,
-              tools: [], signal,
+              tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), signal,
               conversationMode: runtimeContext.conversationMode ?? 'private',
               promptCache: options.promptCache,
             })) {
@@ -1241,11 +1269,8 @@ export async function* runQuery(
                 break;
               }
               if (event.type === 'text_delta') {
-                // Never expose a rewrite of the reviewed candidate. Previously
-                // published chunks are necessarily an exact prefix of it.
-                if (!candidate.startsWith(publishedText + event.delta)) {
-                  throw new Error('发布内容偏离定稿，使用原定稿。');
-                }
+                // Final expression is live generation, not an exact-copy replay.
+                // Once visible, text is never replaced or joined with a different draft.
                 publishedText += event.delta;
                 streamed = true;
                 yield { type: 'text', delta: event.delta };
@@ -1260,23 +1285,19 @@ export async function* runQuery(
             if (!publicationDone && !publicationInterrupted) throw new Error('最终答案流未正常结束。');
             if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length') throw new Error('最终答案流缺少有效的结束状态。');
             if (!publishedText.trim() && !publicationInterrupted) throw new Error('最终表达未返回正文。');
-            if (!publicationInterrupted && publishedText !== candidate) throw new Error('最终表达未完整传递定稿。');
           } catch (error) {
             publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || (error as Error)?.name === 'AbortError';
             publicationError = error;
           }
-          if (publicationError && !publicationInterrupted) {
-            yield { type: 'warning', message: '流式发布未完成，已使用原定稿补齐；未重新生成或改写答案。' };
-            const remaining = candidate.slice(publishedText.length);
-            if (remaining) {
-              yield { type: 'text', delta: remaining };
-              streamed = true;
-            }
+          if (publicationError && !publicationInterrupted && !publishedText) {
+            yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
+            yield { type: 'text', delta: candidate };
+            streamed = true;
             publishedText = candidate;
+            lastFinishReason = candidateFinishReason;
             publicationError = undefined;
           }
           assistantText = publishedText;
-          if (!publicationInterrupted) lastFinishReason = candidateFinishReason;
           assistantMsg.content = publishedText || null;
           if (!publishedText) {
             if (publicationInterrupted) yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };

package/src/memory/fileStore.js

@@ -1,12 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import lockfile from 'proper-lockfile';
 import { chmod, mkdir, open, readFile, rename, rm, 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';
-const LOCK_STALE_MS = 120_000;
-const LOCK_WAIT_MS = 15_000;
 let mutationQueue = Promise.resolve();
 export function memoryRootDir() {
     return join(agentStateDir(), 'memory');
@@ -54,36 +51,7 @@ export async function pathExists(path) {
 export async function acquireFileLock(path, signal) {
     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.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(path, content) {
     await ensurePrivateDir(dirname(path));

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/prompts/policyRegistry.js

@@ -1,6 +1,7 @@
 import { CODE_REVIEW_RUBRIC } from './codeReview.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 +195,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'),
     },

package/src/prompts/policyRegistry.ts

@@ -6,6 +6,8 @@ import {
   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 +33,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 +244,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'),
   },

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',