minimal-agent 0.18.7 → 0.18.8

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/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

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

package/src/runtime/finalAnswer.ts

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

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,

package/src/session/runAgentTurn.ts

@@ -9,10 +9,10 @@ import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { createPromptCacheContext } from '../llm/promptCache.js';
 import { type ModelRef, modelRefFromLegacy } from '../modelRef.js';
 import {
-  buildBaseSystemPrompt,
   browserPromptRuntime,
   buildTransientPromptBundle,
 } from '../prompts/system.js';
+import { assembleStablePrompt } from '../prompts/promptAssembly.js';
 import {
   createAgentRuntimeContext,
   filterToolsForRuntime,
@@ -31,6 +31,7 @@ import {
 } from './sessionState.js';
 
 export interface RunAgentTurnOptions {
+  output?: import('../runtime/outputContract.js').OutputContract;
   /** Host execution identity: distinct triggers must not reuse completed plugin work. */
   executionId?: string;
   input: string;
@@ -178,6 +179,7 @@ export async function runAgentTurn(
     // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
     // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
     const runtimeContext = createAgentRuntimeContext({
+      output: opts.output,
       surface: 'headless',
       profile: 'main',
       cwd: effectiveCwd,
@@ -216,11 +218,14 @@ export async function runAgentTurn(
       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,

package/src/session/runtimeStore.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, readdir, rename, rm, stat, } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { agentStateDir } from '../context/agentHome.js';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 function segment(value, fallback) {
     return ((value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
         fallback);
@@ -20,38 +21,20 @@ export async function withRuntimeFileLock(path, work) {
     const tail = previous.then(() => current);
     queues.set(key, tail);
     await previous.catch(() => undefined);
-    let lockHandle;
-    const lockPath = `${path}.lock`;
+    let unlock;
     try {
-        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-        const deadline = Date.now() + 10_000;
-        while (!lockHandle) {
-            try {
-                lockHandle = await open(lockPath, 'wx', 0o600);
-                await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
-            }
-            catch (error) {
-                if (error.code !== 'EEXIST')
-                    throw error;
-                const age = Date.now() -
-                    (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
-                if (age > 30_000)
-                    await rm(lockPath, { force: true });
-                else if (Date.now() >= deadline)
-                    throw new Error(`runtime lock timeout: ${path}`);
-                else
-                    await new Promise((r) => setTimeout(r, 25));
-            }
-        }
+        unlock = await acquireStateFileLock(key, { label: 'RUNTIME' });
         return await work();
     }
     finally {
-        await lockHandle?.close().catch(() => undefined);
-        if (lockHandle)
-            await rm(lockPath, { force: true }).catch(() => undefined);
-        release();
-        if (queues.get(key) === tail)
-            queues.delete(key);
+        try {
+            await unlock?.();
+        }
+        finally {
+            release();
+            if (queues.get(key) === tail)
+                queues.delete(key);
+        }
     }
 }
 export async function readRuntimeJson(path, fallback) {

package/src/session/runtimeStore.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join, resolve } from 'node:path';
 
 import { agentStateDir } from '../context/agentHome.js';
+import { acquireStateFileLock } from '../runtime/fileLock.js';
 
 export interface RuntimeIdentity {
   workspaceId?: string;
@@ -47,32 +48,17 @@ export async function withRuntimeFileLock<T>(
   const tail = previous.then(() => current);
   queues.set(key, tail);
   await previous.catch(() => undefined);
-  let lockHandle: Awaited<ReturnType<typeof open>> | undefined;
-  const lockPath = `${path}.lock`;
+  let unlock: (() => Promise<void>) | undefined;
   try {
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + 10_000;
-    while (!lockHandle) {
-      try {
-        lockHandle = await open(lockPath, 'wx', 0o600);
-        await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
-        const age =
-          Date.now() -
-          (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
-        if (age > 30_000) await rm(lockPath, { force: true });
-        else if (Date.now() >= deadline)
-          throw new Error(`runtime lock timeout: ${path}`);
-        else await new Promise((r) => setTimeout(r, 25));
-      }
-    }
+    unlock = await acquireStateFileLock(key, { label: 'RUNTIME' });
     return await work();
   } finally {
-    await lockHandle?.close().catch(() => undefined);
-    if (lockHandle) await rm(lockPath, { force: true }).catch(() => undefined);
-    release();
-    if (queues.get(key) === tail) queues.delete(key);
+    try {
+      await unlock?.();
+    } finally {
+      release();
+      if (queues.get(key) === tail) queues.delete(key);
+    }
   }
 }