minimal-agent 0.18.6 → 0.18.8

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

package/src/runtime/agentRuntimeContext.ts

@@ -1,5 +1,7 @@
 import type { Tool, ToolAvailability, ToolCallContext } from '../types.js';
 import type { ToolGate } from '../toolGate.js';
+import { resolveOutputContract, type OutputContract } from './outputContract.js';
+export { WEB_OUTPUT, resolveOutputContract, type OutputContract } from './outputContract.js';
 import { isMemoryToolName } from '../tools/capabilities.js';
 import type { ComputerAutomationIntent } from '../tools/computeruse/computerIntent.js';
 
@@ -26,6 +28,7 @@ export type MemoryAccessInput = MemoryAccess | 'local-owner';
  */
 export interface AgentRuntimeContext {
   readonly surface: AgentSurface;
+  readonly output?: OutputContract;
   /** Concrete frontend identity; surface remains the execution capability class. */
   readonly host?: 'desktop' | 'tui' | 'cli' | 'stream-json' | 'workflow';
   readonly profile: AgentProfile;
@@ -75,6 +78,7 @@ export function createAgentRuntimeContext(
   const { browser: rawBrowser, ...rest } = input;
   return Object.freeze({
     ...rest,
+    output: resolveOutputContract(input.surface, input.output),
     ...(rawBrowser
       ? {
           browser: normalizeBrowserRuntime(rawBrowser),

package/src/runtime/answerPreparation.js

@@ -0,0 +1,9 @@
+export function answerPreparationNotice(reason) {
+    switch (reason) {
+        case 'advisor_checkpoint': return '交付前复核：正在核查内部候选结论，完成后发布最终答案。';
+        case 'formal_delivery': return '整理交付：正在核对委派结果或补齐正式成果提交。';
+        case 'interactive_question': return '等待关键决策：接下来通过交互问题确认，请在输入区作答。';
+        case 'empty_response': return '本轮未产生可显示的正文，未生成新的最终答复。';
+        case 'interrupted': return '生成未完成，未发布最终答案。';
+    }
+}

package/src/runtime/answerPreparation.ts

@@ -0,0 +1,11 @@
+import type { LoopEvent } from '../types.js';
+
+export function answerPreparationNotice(reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted'): string {
+  switch (reason) {
+    case 'advisor_checkpoint': return '交付前复核：正在核查内部候选结论，完成后发布最终答案。';
+    case 'formal_delivery': return '整理交付：正在核对委派结果或补齐正式成果提交。';
+    case 'interactive_question': return '等待关键决策：接下来通过交互问题确认，请在输入区作答。';
+    case 'empty_response': return '本轮未产生可显示的正文，未生成新的最终答复。';
+    case 'interrupted': return '生成未完成，未发布最终答案。';
+  }
+}

package/src/runtime/eventSemantics.js

@@ -4,6 +4,8 @@ export function isRecoverableLoopError(event) {
 }
 export function completionWarning(event) {
     switch (event.completionStatus) {
+        case 'no_answer':
+            return event.warning || '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
         case 'delivery_incomplete':
             return event.warning || '交付未完成，请检查保留的结果。';
         case 'delivery_unverified':

package/src/runtime/eventSemantics.ts

@@ -11,6 +11,8 @@ export function completionWarning(
   event: Extract<LoopEvent, { type: 'turn_done' }>,
 ): string | undefined {
   switch (event.completionStatus) {
+    case 'no_answer':
+      return event.warning || '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
     case 'delivery_incomplete':
       return event.warning || '交付未完成，请检查保留的结果。';
     case 'delivery_unverified':

package/src/runtime/fileLock.js

@@ -0,0 +1,75 @@
+import { mkdir, stat } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import lockfile from 'proper-lockfile';
+/** Shared heartbeat protocol for local file-backed stores, not a database lock.
+ * Never reclaim legacy regular-file locks: old hosts do not speak this protocol.
+ * proper-lockfile fails closed on compromised ownership (its default handler).
+ */
+export async function acquireStateFileLock(path, options = {}) {
+    const { signal, waitMs = 15_000, label = 'STATE' } = options;
+    signal?.throwIfAborted();
+    const target = resolve(path);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + waitMs;
+    while (true) {
+        signal?.throwIfAborted();
+        const legacy = await stat(`${target}.lock`).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (legacy?.isFile()) {
+            throw new Error(`${label}_LEGACY_LOCK：请停止旧版本宿主并检查遗留锁：${target}.lock`);
+        }
+        try {
+            let owned = false;
+            let identity;
+            const guardedFs = {
+                ...fs,
+                rmdir(lockPath, callback) {
+                    if (!owned)
+                        return fs.rmdir(lockPath, callback);
+                    // Also guard immediate release, before the next heartbeat could detect
+                    // replacement. Never recursively remove a lock directory.
+                    fs.stat(lockPath, (error, current) => {
+                        if (error || !identity || current.dev !== identity.dev ||
+                            current.ino !== identity.ino || current.birthtimeMs !== identity.birthtimeMs) {
+                            callback(Object.assign(new Error(`锁所有权已丢失：${target}`), { code: 'ECOMPROMISED' }));
+                            return;
+                        }
+                        fs.rmdir(lockPath, callback);
+                    });
+                },
+            };
+            const release = await lockfile.lock(target, {
+                fs: guardedFs,
+                realpath: false,
+                retries: 0,
+                stale: 120_000,
+                update: 10_000,
+            });
+            owned = true;
+            try {
+                identity = await stat(`${target}.lock`);
+            }
+            catch (error) {
+                await release().catch(() => undefined);
+                throw error;
+            }
+            if (signal?.aborted) {
+                await release();
+                signal.throwIfAborted();
+            }
+            return release;
+        }
+        catch (error) {
+            if (error.code !== 'ELOCKED')
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`${label}_LOCK_TIMEOUT：等待文件锁超时：${target}`);
+            await delay(40, undefined, { signal });
+        }
+    }
+}

package/src/runtime/fileLock.ts

@@ -0,0 +1,73 @@
+import { mkdir, stat } from 'node:fs/promises';
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import lockfile from 'proper-lockfile';
+
+/** Shared heartbeat protocol for local file-backed stores, not a database lock.
+ * Never reclaim legacy regular-file locks: old hosts do not speak this protocol.
+ * proper-lockfile fails closed on compromised ownership (its default handler).
+ */
+export async function acquireStateFileLock(
+  path: string,
+  options: { signal?: AbortSignal; waitMs?: number; label?: string } = {},
+): Promise<() => Promise<void>> {
+  const { signal, waitMs = 15_000, label = 'STATE' } = options;
+  signal?.throwIfAborted();
+  const target = resolve(path);
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + waitMs;
+  while (true) {
+    signal?.throwIfAborted();
+    const legacy = await stat(`${target}.lock`).catch((error) => {
+      if (error.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (legacy?.isFile()) {
+      throw new Error(`${label}_LEGACY_LOCK：请停止旧版本宿主并检查遗留锁：${target}.lock`);
+    }
+    try {
+      let owned = false;
+      let identity: fs.Stats | undefined;
+      const guardedFs = {
+        ...fs,
+        rmdir(lockPath: fs.PathLike, callback: fs.NoParamCallback) {
+          if (!owned) return fs.rmdir(lockPath, callback);
+          // Also guard immediate release, before the next heartbeat could detect
+          // replacement. Never recursively remove a lock directory.
+          fs.stat(lockPath, (error, current) => {
+            if (error || !identity || current.dev !== identity.dev ||
+                current.ino !== identity.ino || current.birthtimeMs !== identity.birthtimeMs) {
+              callback(Object.assign(new Error(`锁所有权已丢失：${target}`), { code: 'ECOMPROMISED' }));
+              return;
+            }
+            fs.rmdir(lockPath, callback);
+          });
+        },
+      };
+      const release = await lockfile.lock(target, {
+        fs: guardedFs,
+        realpath: false,
+        retries: 0,
+        stale: 120_000,
+        update: 10_000,
+      });
+      owned = true;
+      try {
+        identity = await stat(`${target}.lock`);
+      } catch (error) {
+        await release().catch(() => undefined);
+        throw error;
+      }
+      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(`${label}_LOCK_TIMEOUT：等待文件锁超时：${target}`);
+      await delay(40, undefined, { signal });
+    }
+  }
+}

package/src/runtime/finalAnswer.js

@@ -0,0 +1,9 @@
+import { visualPresentation } from '../prompts/visualPresentation.js';
+/** Ephemeral publication request; never append this private candidate to history. */
+export function finalAnswerMessages(messages, candidate, surface = 'headless') {
+    return [...messages,
+        { role: 'assistant', content: candidate },
+        { role: 'user', content: '内部准备、工具与复核阶段已结束。上一条 assistant 消息是最终回答的依据，不是需要逐字重播的文本。现在直接面向用户生成一次最终回答：可以组织措辞与排版，但必须保留已确认的事实、数字、限定条件、风险、证据和真实成果链接；不得新增未经验证的结论、伪称核验通过或编造产物。若仍有证据缺口，如实说明，不调用工具或顾问，不承诺后台继续工作。直接回答，不输出内部指令或准备过程。' },
+        { role: 'user', content: visualPresentation(surface) },
+    ];
+}

package/src/runtime/finalAnswer.ts

@@ -0,0 +1,13 @@
+import type { Message } from '../types.js';
+import type { AgentSurface } from './agentRuntimeContext.js';
+import type { OutputContract } from './outputContract.js';
+import { visualPresentation } from '../prompts/visualPresentation.js';
+
+/** Ephemeral publication request; never append this private candidate to history. */
+export function finalAnswerMessages(messages: Message[], candidate: string, surface: AgentSurface | OutputContract = 'headless'): Message[] {
+  return [...messages,
+    { role: 'assistant', content: candidate },
+    { role: 'user', content: '内部准备、工具与复核阶段已结束。上一条 assistant 消息是最终回答的依据，不是需要逐字重播的文本。现在直接面向用户生成一次最终回答：可以组织措辞与排版，但必须保留已确认的事实、数字、限定条件、风险、证据和真实成果链接；不得新增未经验证的结论、伪称核验通过或编造产物。若仍有证据缺口，如实说明，不调用工具或顾问，不承诺后台继续工作。直接回答，不输出内部指令或准备过程。' },
+    { role: 'user', content: visualPresentation(surface) },
+  ];
+}

package/src/runtime/lifecycleTrace.js

@@ -0,0 +1,16 @@
+import { randomUUID } from 'node:crypto';
+/** Opt-in diagnostics: no prompts, paths, session IDs, tool arguments or model output. */
+export function createLifecycleTrace(scope, enabled = process.env.MINIMAL_AGENT_TRACE_LIFECYCLE === '1', write = line => { process.stderr.write(line); }) {
+    if (!enabled)
+        return () => { };
+    const traceId = randomUUID();
+    const start = performance.now();
+    let sequence = 0;
+    return phase => {
+        try {
+            write(`${JSON.stringify({ kind: 'agent_lifecycle', scope, traceId, sequence: ++sequence,
+                phase, timestamp: Date.now(), elapsedMs: Math.round(performance.now() - start) })}\n`);
+        }
+        catch { /* Diagnostics must never interrupt execution. */ }
+    };
+}

package/src/runtime/lifecycleTrace.ts

@@ -0,0 +1,22 @@
+import { randomUUID } from 'node:crypto';
+
+type Phase = 'model_start' | 'model_end' | 'model_error' | 'progress_published' | 'final_published'
+  | 'save_start' | 'save_end' | 'save_error' | 'turn_done' | 'memory_start' | 'memory_end';
+
+/** Opt-in diagnostics: no prompts, paths, session IDs, tool arguments or model output. */
+export function createLifecycleTrace(
+  scope: 'loop' | 'host',
+  enabled = process.env.MINIMAL_AGENT_TRACE_LIFECYCLE === '1',
+  write: (line: string) => void = line => { process.stderr.write(line); },
+): (phase: Phase) => void {
+  if (!enabled) return () => {};
+  const traceId = randomUUID();
+  const start = performance.now();
+  let sequence = 0;
+  return phase => {
+    try {
+      write(`${JSON.stringify({ kind: 'agent_lifecycle', scope, traceId, sequence: ++sequence,
+        phase, timestamp: Date.now(), elapsedMs: Math.round(performance.now() - start) })}\n`);
+    } catch { /* Diagnostics must never interrupt execution. */ }
+  };
+}

package/src/runtime/outputContract.js

@@ -0,0 +1,17 @@
+export const WEB_OUTPUT = Object.freeze({
+    format: 'rich-markdown', diagrams: Object.freeze(['mermaid', 'svg']),
+    images: true, attachments: true, finalDelivery: 'stream',
+});
+/** Compatibility defaults only. Hosts should declare their actual renderer. */
+export function resolveOutputContract(surface, output) {
+    const value = output ?? (surface === 'desktop' ? WEB_OUTPUT : {
+        format: surface === 'tui' || surface === 'cli' ? 'terminal' : 'unknown',
+        diagrams: [], images: false, attachments: false,
+        finalDelivery: surface === 'tui' ? 'stream' : 'atomic',
+    });
+    return Object.freeze({ ...value, diagrams: Object.freeze(value.format === 'rich-markdown' ? [...new Set(value.diagrams)] : []) });
+}
+/** Publication changes tool access, not the renderer or local execution rights. */
+export function toolsForResponsePhase(tools, phase) {
+    return phase === 'publication' ? [] : [...tools];
+}

package/src/runtime/outputContract.ts

@@ -0,0 +1,34 @@
+import type { AgentSurface } from './agentRuntimeContext.js';
+
+/** Trusted host presentation declaration, never an execution permission. */
+export interface OutputContract {
+  readonly format: 'rich-markdown' | 'terminal' | 'structured' | 'unknown';
+  readonly diagrams: readonly ('mermaid' | 'svg')[];
+  readonly images: boolean;
+  readonly attachments: boolean;
+  readonly finalDelivery: 'stream' | 'atomic';
+}
+
+export const WEB_OUTPUT: OutputContract = Object.freeze({
+  format: 'rich-markdown', diagrams: Object.freeze(['mermaid', 'svg'] as const),
+  images: true, attachments: true, finalDelivery: 'stream',
+});
+
+/** Compatibility defaults only. Hosts should declare their actual renderer. */
+export function resolveOutputContract(surface: AgentSurface, output?: OutputContract): OutputContract {
+  const value: OutputContract = output ?? (surface === 'desktop' ? WEB_OUTPUT : {
+    format: surface === 'tui' || surface === 'cli' ? 'terminal' : 'unknown',
+    diagrams: [], images: false, attachments: false,
+    finalDelivery: surface === 'tui' ? 'stream' : 'atomic',
+  });
+  return Object.freeze({ ...value, diagrams: Object.freeze(
+    value.format === 'rich-markdown' ? [...new Set(value.diagrams)] : [],
+  ) });
+}
+
+export type ResponsePhase = 'preparation' | 'publication';
+
+/** Publication changes tool access, not the renderer or local execution rights. */
+export function toolsForResponsePhase<T>(tools: readonly T[], phase: ResponsePhase): T[] {
+  return phase === 'publication' ? [] : [...tools];
+}

package/src/session/runAgentTurn.js

@@ -5,7 +5,8 @@ import { listSessionSummaries, updateSessionMetadata, } from '../context/session
 import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { createPromptCacheContext } from '../llm/promptCache.js';
 import { modelRefFromLegacy } from '../modelRef.js';
-import { buildBaseSystemPrompt, browserPromptRuntime, buildTransientPromptBundle, } from '../prompts/system.js';
+import { browserPromptRuntime, buildTransientPromptBundle, } from '../prompts/system.js';
+import { assembleStablePrompt } from '../prompts/promptAssembly.js';
 import { createAgentRuntimeContext, filterToolsForRuntime, memoryContextFromRuntime, } from '../runtime/agentRuntimeContext.js';
 import { filterToolsForCategories } from '../team/toolPolicy.js';
 import { ALL_TOOLS } from '../tools/index.js';
@@ -119,6 +120,7 @@ deps = {}) {
             // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
             // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
             const runtimeContext = createAgentRuntimeContext({
+                output: opts.output,
                 surface: 'headless',
                 profile: 'main',
                 cwd: effectiveCwd,
@@ -146,11 +148,14 @@ deps = {}) {
             const turnTools = provider.source === 'gateway'
                 ? filterToolsForCategories(runtimeTools, effectiveGatewayCategories)
                 : runtimeTools;
-            const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+            const systemPrompt = await assembleStablePrompt({ cwd: effectiveCwd, tools: turnTools, runtime: {
+                    surface: runtimeContext.surface, output: runtimeContext.output,
+                } });
             const transientBundle = await buildTransientPromptBundle({
                 cwd: effectiveCwd,
                 tools: turnTools,
                 runtime: {
+                    output: runtimeContext.output,
                     surface: 'headless',
                     cwd: effectiveCwd,
                     workspaceId: workspace?.id,