minimal-agent 0.10.0 → 0.12.0

package/src/runtime/agentRuntimeContext.ts

@@ -0,0 +1,112 @@
+import type { Tool, ToolAvailability, ToolCallContext } from '../types.js';
+import type { ToolGate } from '../toolGate.js';
+import { isMemoryToolName } from '../tools/capabilities.js';
+
+export type AgentSurface =
+  | 'desktop'
+  | 'tui'
+  | 'cli'
+  | 'headless'
+  | 'workflow'
+  | 'subagent';
+
+export type AgentProfile = 'main' | 'subagent-explore' | 'subagent-general';
+export type AgentOwner = 'local-owner' | 'untrusted';
+export type MemoryAccess = 'read-write' | 'read-only' | 'denied';
+export type MemoryAccessInput = MemoryAccess | 'local-owner';
+
+/**
+ * Host-issued trust context for one agent run.  Nothing in this object may be
+ * inferred from model output, project files, tools, or web content.
+ */
+export interface AgentRuntimeContext {
+  readonly surface: AgentSurface;
+  readonly profile: AgentProfile;
+  readonly cwd: string;
+  readonly workspaceId?: string;
+  readonly sessionId?: string;
+  readonly owner: AgentOwner;
+  readonly memoryAccess: MemoryAccess;
+  readonly interactiveAsk: boolean;
+  readonly browser?: ToolCallContext['browserRun'];
+  readonly computer?: ToolCallContext['computerRun'];
+  readonly computerIntervention?: ToolCallContext['computerIntervention'];
+  readonly toolGate?: ToolGate;
+}
+
+export interface AgentRuntimeContextInput
+  extends Omit<AgentRuntimeContext, 'owner' | 'memoryAccess'> {
+  owner?: AgentOwner;
+  memoryAccess?: MemoryAccessInput;
+}
+
+export function normalizeMemoryAccess(
+  access: MemoryAccessInput | undefined,
+): MemoryAccess {
+  return access === 'local-owner' ? 'read-write' : access ?? 'denied';
+}
+
+/** Only a local owner can receive memory access; untrusted hosts are always denied. */
+export function createAgentRuntimeContext(
+  input: AgentRuntimeContextInput,
+): Readonly<AgentRuntimeContext> {
+  const owner = input.owner ?? 'untrusted';
+  const memoryAccess = owner === 'local-owner'
+    ? normalizeMemoryAccess(input.memoryAccess)
+    : 'denied';
+  return Object.freeze({
+    ...input,
+    owner,
+    memoryAccess,
+  });
+}
+
+export function filterToolsForRuntime(
+  tools: readonly Tool[],
+  runtime: Pick<AgentRuntimeContext, 'surface' | 'profile' | 'cwd' | 'memoryAccess' | 'browser' | 'computer'>,
+  resolvedAvailability?: ReadonlyMap<Tool, ToolAvailability>,
+): Tool[] {
+  return tools.filter((tool) =>
+    (resolvedAvailability?.get(tool)?.available
+      ?? tool.resolveAvailability?.(runtime as AgentRuntimeContext).available
+      ?? true)
+    && (memoryToolAllowed(tool.name, runtime.memoryAccess))
+    && (tool.name !== 'WebBrowser' || webBrowserAllowed(runtime))
+    && (tool.name !== 'ComputerUse' || runtime.computer !== undefined));
+}
+
+/** WebBrowser is the Desktop main Agent's visible, human-supervised automation surface. */
+export function webBrowserAllowed(
+  runtime: Pick<AgentRuntimeContext, 'surface' | 'profile' | 'browser'>,
+): boolean {
+  return runtime.surface === 'desktop'
+    && runtime.profile === 'main'
+    && runtime.browser?.supervised === true;
+}
+
+const READ_ONLY_MEMORY_TOOLS = new Set([
+  'RecallMemory',
+  'ListMemories',
+  'ReviewMemories',
+  'SearchConversations',
+]);
+
+export function memoryToolAllowed(name: string, access: MemoryAccess): boolean {
+  if (!isMemoryToolName(name)) return true;
+  if (access === 'read-write') return true;
+  return access === 'read-only' && READ_ONLY_MEMORY_TOOLS.has(name);
+}
+
+export function isMemoryTool(name: string): boolean {
+  return isMemoryToolName(name);
+}
+
+export function memoryContextFromRuntime(
+  runtime: AgentRuntimeContext,
+): { access: MemoryAccess; workspaceId?: string; sessionId?: string } {
+  return {
+    access: runtime.memoryAccess,
+    ...(runtime.workspaceId ? { workspaceId: runtime.workspaceId } : {}),
+    ...(runtime.sessionId ? { sessionId: runtime.sessionId } : {}),
+  };
+}

package/src/session/runAgentTurn.js

@@ -1,12 +1,15 @@
-import { buildFullSystemPrompt } from '../prompts/system.js';
+import { buildBaseSystemPrompt, buildTransientPromptBundle, } from '../prompts/system.js';
 import { ALL_TOOLS } from '../tools/index.js';
 import { sessionFileFor } from '../context/sessionPath.js';
-import { createSessionState } from './sessionState.js';
+import { getOrCreateSessionState, sessionStateKey, } from './sessionState.js';
+import { hydrateSessionWorktree } from '../tools/worktree/sessionWorktree.js';
 import { runTurn } from './runTurn.js';
 import { withWorkingDir } from '../bootstrap/workingDir.js';
-import { listSessionSummaries, updateSessionMetadata } from '../context/sessionRegistry.js';
+import { listSessionSummaries, updateSessionMetadata, } from '../context/sessionRegistry.js';
 import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { configService } from '../config/configService.js';
+import { createPromptCacheContext } from '../llm/promptCache.js';
+import { createAgentRuntimeContext, filterToolsForRuntime, memoryContextFromRuntime, } from '../runtime/agentRuntimeContext.js';
 export async function runAgentTurn(opts, 
 // DI 缝（仿 agent.ts 的 deps 先例）：compact_failed 无法经 chat DI 触发
 // （压缩走模块级 chat，见 test/loop.errorCode.test.ts 头注），测试注入假 runTurn。
@@ -15,9 +18,12 @@ deps = {}) {
     const session = (await listSessionSummaries(opts.cwd)).find((item) => item.id === opts.sessionId);
     let sessionModelId = session?.modelId;
     if (!opts.model && !sessionModelId) {
-        sessionModelId = (await configService.getSnapshot()).config?.baseModelId ?? undefined;
+        sessionModelId =
+            (await configService.getSnapshot()).config?.baseModelId ?? undefined;
         if (sessionModelId) {
-            await updateSessionMetadata(opts.cwd, opts.sessionId, { modelId: sessionModelId }).catch(() => { });
+            await updateSessionMetadata(opts.cwd, opts.sessionId, {
+                modelId: sessionModelId,
+            }).catch(() => { });
         }
     }
     const sessionProvider = !opts.model && sessionModelId
@@ -25,24 +31,75 @@ deps = {}) {
         : null;
     const provider = opts.model
         ? { ...opts.provider, model: opts.model }
-        : sessionProvider ?? opts.provider;
-    await workspaceIndexService.register(opts.cwd).catch(() => { });
+        : (sessionProvider ?? opts.provider);
+    const workspace = await workspaceIndexService
+        .register(opts.cwd)
+        .catch(() => undefined);
     const sessionFile = sessionFileFor(opts.cwd, opts.sessionId);
-    const systemPrompt = await buildFullSystemPrompt(opts.cwd, ALL_TOOLS);
     const events = [];
     let result = '';
     let error;
     let numTurns = 0;
-    await withWorkingDir(opts.cwd, async () => {
-        await updateSessionMetadata(opts.cwd, opts.sessionId, { lastMessagePreview: opts.input }).catch(() => { });
+    const turnSessionState = opts.sessionState ??
+        getOrCreateSessionState(sessionStateKey({
+            surface: 'headless',
+            workspaceId: workspace?.id,
+            cwd: workspace?.id ? undefined : opts.cwd,
+            sessionId: opts.sessionId,
+        }));
+    await hydrateSessionWorktree({
+        sessionState: turnSessionState,
+        workspaceId: workspace?.id,
+        sessionId: opts.sessionId,
+        cwd: opts.cwd,
+    });
+    const effectiveCwd = turnSessionState.activeWorktree?.path ?? opts.cwd;
+    await withWorkingDir(effectiveCwd, async () => {
+        // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
+        // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
+        const runtimeContext = createAgentRuntimeContext({
+            surface: 'headless',
+            profile: 'main',
+            cwd: effectiveCwd,
+            workspaceId: workspace?.id,
+            sessionId: opts.sessionId,
+            owner: opts.memoryAccess && opts.memoryAccess !== 'denied'
+                ? 'local-owner'
+                : 'untrusted',
+            memoryAccess: opts.memoryAccess ?? 'denied',
+            interactiveAsk: false,
+        });
+        const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
+        const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+        const transientBundle = await buildTransientPromptBundle({
+            cwd: effectiveCwd,
+            tools: turnTools,
+            runtime: {
+                surface: 'headless',
+                cwd: effectiveCwd,
+                workspaceId: workspace?.id,
+                sessionId: opts.sessionId,
+                interactiveAsk: false,
+                memoryAccess: runtimeContext.memoryAccess,
+                currentUserInput: opts.input,
+            },
+        }).catch(() => undefined);
+        await updateSessionMetadata(opts.cwd, opts.sessionId, {
+            lastMessagePreview: opts.input,
+        }).catch(() => { });
         for await (const ev of run({
             userInput: opts.input,
             provider,
             sessionFile,
             systemPrompt,
-            sessionState: createSessionState(),
+            ...(transientBundle ? { transientBundle } : {}),
+            promptCache: createPromptCacheContext(`workspace:${workspace?.id ?? opts.cwd}:session:${opts.sessionId}`),
+            sessionState: turnSessionState,
             signal: opts.signal,
             maxTurns: opts.maxTurns,
+            runtimeContext,
+            allowedTools: turnTools.map((tool) => tool.name),
+            memoryContext: memoryContextFromRuntime(runtimeContext),
         })) {
             if (isEventLike(ev)) {
                 events.push(ev);
@@ -66,5 +123,7 @@ deps = {}) {
     };
 }
 function isEventLike(ev) {
-    return Boolean(ev && typeof ev === 'object' && typeof ev.type === 'string');
+    return Boolean(ev &&
+        typeof ev === 'object' &&
+        typeof ev.type === 'string');
 }

package/src/session/runAgentTurn.ts

@@ -0,0 +1,181 @@
+import {
+  buildBaseSystemPrompt,
+  buildTransientPromptBundle,
+} from '../prompts/system.js';
+import { ALL_TOOLS } from '../tools/index.js';
+import type { LoopEvent, Provider } from '../types.js';
+import { sessionFileFor } from '../context/sessionPath.js';
+import {
+  getOrCreateSessionState,
+  sessionStateKey,
+  type SessionState,
+} from './sessionState.js';
+import { hydrateSessionWorktree } from '../tools/worktree/sessionWorktree.js';
+import { runTurn } from './runTurn.js';
+import { withWorkingDir } from '../bootstrap/workingDir.js';
+import {
+  listSessionSummaries,
+  updateSessionMetadata,
+} from '../context/sessionRegistry.js';
+import { workspaceIndexService } from '../context/workspaceIndex.js';
+import { configService } from '../config/configService.js';
+import { createPromptCacheContext } from '../llm/promptCache.js';
+import {
+  createAgentRuntimeContext,
+  filterToolsForRuntime,
+  memoryContextFromRuntime,
+} from '../runtime/agentRuntimeContext.js';
+
+export interface RunAgentTurnOptions {
+  input: string;
+  provider: Provider;
+  cwd: string;
+  sessionId: string;
+  maxTurns?: number;
+  model?: string;
+  signal?: AbortSignal;
+  /** Generic headless callers must declare local memory access explicitly. */
+  memoryAccess?: import('../runtime/agentRuntimeContext.js').MemoryAccessInput;
+  /** Advanced hosts may own the session lifecycle explicitly. */
+  sessionState?: SessionState;
+}
+
+export interface RunAgentTurnResult {
+  ok: boolean;
+  result: string;
+  error?: string;
+  numTurns: number;
+  events: Array<{ type: string; [key: string]: unknown }>;
+}
+
+export async function runAgentTurn(
+  opts: RunAgentTurnOptions,
+  // DI 缝（仿 agent.ts 的 deps 先例）：compact_failed 无法经 chat DI 触发
+  // （压缩走模块级 chat，见 test/loop.errorCode.test.ts 头注），测试注入假 runTurn。
+  deps: { runTurn?: typeof runTurn } = {},
+): Promise<RunAgentTurnResult> {
+  const run = deps.runTurn ?? runTurn;
+  const session = (await listSessionSummaries(opts.cwd)).find(
+    (item) => item.id === opts.sessionId,
+  );
+  let sessionModelId = session?.modelId;
+  if (!opts.model && !sessionModelId) {
+    sessionModelId =
+      (await configService.getSnapshot()).config?.baseModelId ?? undefined;
+    if (sessionModelId) {
+      await updateSessionMetadata(opts.cwd, opts.sessionId, {
+        modelId: sessionModelId,
+      }).catch(() => {});
+    }
+  }
+  const sessionProvider =
+    !opts.model && sessionModelId
+      ? await configService.providerForModel(sessionModelId)
+      : null;
+  const provider = opts.model
+    ? { ...opts.provider, model: opts.model }
+    : (sessionProvider ?? opts.provider);
+  const workspace = await workspaceIndexService
+    .register(opts.cwd)
+    .catch(() => undefined);
+  const sessionFile = sessionFileFor(opts.cwd, opts.sessionId);
+  const events: LoopEvent[] = [];
+  let result = '';
+  let error: string | undefined;
+  let numTurns = 0;
+  const turnSessionState =
+    opts.sessionState ??
+    getOrCreateSessionState(
+      sessionStateKey({
+        surface: 'headless',
+        workspaceId: workspace?.id,
+        cwd: workspace?.id ? undefined : opts.cwd,
+        sessionId: opts.sessionId,
+      }),
+    );
+  await hydrateSessionWorktree({
+    sessionState: turnSessionState,
+    workspaceId: workspace?.id,
+    sessionId: opts.sessionId,
+    cwd: opts.cwd,
+  });
+  const effectiveCwd = turnSessionState.activeWorktree?.path ?? opts.cwd;
+
+  await withWorkingDir(effectiveCwd, async () => {
+    // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
+    // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
+    const runtimeContext = createAgentRuntimeContext({
+      surface: 'headless',
+      profile: 'main',
+      cwd: effectiveCwd,
+      workspaceId: workspace?.id,
+      sessionId: opts.sessionId,
+      owner:
+        opts.memoryAccess && opts.memoryAccess !== 'denied'
+          ? 'local-owner'
+          : 'untrusted',
+      memoryAccess: opts.memoryAccess ?? 'denied',
+      interactiveAsk: false,
+    });
+    const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
+    const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+    const transientBundle = await buildTransientPromptBundle({
+      cwd: effectiveCwd,
+      tools: turnTools,
+      runtime: {
+        surface: 'headless',
+        cwd: effectiveCwd,
+        workspaceId: workspace?.id,
+        sessionId: opts.sessionId,
+        interactiveAsk: false,
+        memoryAccess: runtimeContext.memoryAccess,
+        currentUserInput: opts.input,
+      },
+    }).catch(() => undefined);
+    await updateSessionMetadata(opts.cwd, opts.sessionId, {
+      lastMessagePreview: opts.input,
+    }).catch(() => {});
+    for await (const ev of run({
+      userInput: opts.input,
+      provider,
+      sessionFile,
+      systemPrompt,
+      ...(transientBundle ? { transientBundle } : {}),
+      promptCache: createPromptCacheContext(
+        `workspace:${workspace?.id ?? opts.cwd}:session:${opts.sessionId}`,
+      ),
+      sessionState: turnSessionState,
+      signal: opts.signal,
+      maxTurns: opts.maxTurns,
+      runtimeContext,
+      allowedTools: turnTools.map((tool) => tool.name),
+      memoryContext: memoryContextFromRuntime(runtimeContext),
+    })) {
+      if (isEventLike(ev)) {
+        events.push(ev);
+        if (ev.type === 'text') result += ev.delta;
+        if (ev.type === 'assistant_message') numTurns++;
+        // compact_failed 是非致命（loop 压缩失败后 snip 兜底继续跑完，types.ts 有约定；
+        // print.ts 同样特判）——不置 error，否则 cron 会把自愈轮误判失败。
+        if (ev.type === 'error' && ev.code !== 'compact_failed')
+          error = ev.error;
+      }
+    }
+  });
+
+  return {
+    ok: !error,
+    result,
+    ...(error ? { error } : {}),
+    numTurns,
+    events,
+  };
+}
+
+function isEventLike(ev: unknown): ev is LoopEvent {
+  return Boolean(
+    ev &&
+    typeof ev === 'object' &&
+    typeof (ev as { type?: unknown }).type === 'string',
+  );
+}

package/src/session/runTurn.js

@@ -20,6 +20,7 @@
  */
 import { loadContext, saveContext } from '../context/persistContext.js';
 import { acquireContextLock } from '../context/contextLock.js';
+import { startTurnJournal } from '../memory/turnJournal.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
 /**
  * 已有历史时，用调用方新算好的 systemPrompt（含当前日期/实时扫描的 skills·plugins 清单/
@@ -30,6 +31,14 @@ import { runWithPlugins } from '../plugins/pluginRunner.js';
  * plugins/项目指令都不会再刷新，与"运行时实时扫描"的设计承诺矛盾。
  *
  * 没有 loaded（全新会话）走原逻辑；调用方未传 systemPrompt 时不触碰已有历史（向后兼容）。
+ *
+ * ★ 提示词缓存不变量：调用方传进来的 systemPrompt **必须是稳定层**
+ *   （buildBaseSystemPrompt，不含日期/Advisor 状态/记忆召回）。否则这里每轮重写
+ *   history[0] 就会让 system 消息字节逐轮变化，provider 的前缀缓存从第一个 token
+ *   起全部失配 —— 本函数是 headless/cron/Desktop 路径上最隐蔽的一处缓存杀手。
+ *   易变内容改走 opts.transientContext（loop 只装饰当前用户消息的模型副本）。
+ *   稳定层是确定性的，所以这里的"每轮刷新"退化成逐字节相同的 no-op，
+ *   既保住了"运行时实时扫描"的承诺，又不破坏缓存。
  */
 function buildInitialHistory(loaded, systemPrompt) {
     if (!loaded) {
@@ -45,27 +54,47 @@ export async function* runTurn(opts) {
     const release = persist ? await acquireContextLock(opts.sessionFile, opts.signal) : async () => { };
     const loaded = opts.initialHistory ?? (persist ? await loadContext(opts.sessionFile) : null);
     const history = buildInitialHistory(loaded, opts.systemPrompt);
+    const historyStart = history.length;
+    // 会话原文记账：实现在 src/memory/turnJournal.ts（TUI 的 useChat 用同一份），
+    // 刻意不下沉到 runQuery —— 子 Agent 与 workflow 步也调 runQuery，记在那里会把
+    // 子任务提示词当成"用户说的话"污染历史检索。
+    const journal = await startTurnJournal({
+        memoryContext: opts.memoryContext,
+        userInput: opts.userInput,
+        ...(opts.userMessageId ? { userMessageId: opts.userMessageId } : {}),
+    });
     try {
         yield* runWithPlugins(opts.userInput, {
             provider: opts.provider,
             history,
             signal: opts.signal,
             maxTurns: opts.maxTurns,
+            runtimeContext: opts.runtimeContext,
+            allowedTools: opts.allowedTools,
             sessionState: opts.sessionState,
             chat: opts.chat,
             executeTool: opts.executeTool,
+            commitFormalDelivery: opts.commitFormalDelivery,
             toolGate: opts.toolGate,
             transientContext: opts.transientContext,
+            transientBundle: opts.transientBundle,
+            promptCache: opts.promptCache,
             userAttachments: opts.userAttachments,
+            userMessageId: opts.userMessageId,
+            userBrowserReferences: opts.userBrowserReferences,
             imageInputs: opts.imageInputs,
             parseInlineImages: opts.parseInlineImages,
             imageDetail: opts.imageDetail,
             imageMaxLongSidePixel: opts.imageMaxLongSidePixel,
             browserRun: opts.browserRun,
+            computerRun: opts.computerRun,
+            computerIntervention: opts.computerIntervention,
+            memoryContext: opts.memoryContext,
         });
     }
     finally {
         try {
+            await journal?.finish(history, historyStart);
             if (persist)
                 await saveContext(history, opts.sessionFile);
         }

package/src/session/runTurn.ts

@@ -0,0 +1,160 @@
+/**
+ * ============================================================
+ *  src/session/runTurn.ts —— Headless 单 turn 执行器
+ * ------------------------------------------------------------
+ *  把"读 session 文件 → 跑 runQuery → 写 session 文件"封装成单一入口。
+ *  PR 4 HTTP server 的每个请求 handler 用它即可，无需自己拼装。
+ *
+ *  调用方契约：
+ *    - sessionFile: per-chat 隔离的上下文文件路径（参见 sessionPath.sessionFileFor）
+ *    - systemPrompt: 当 loadContext 返回 null（首次会话）时用它建初始 history；
+ *      未提供则用空数组开局（少数 case 才合理，例如不需要 system prompt）
+ *    - sessionState: 多并发场景必须 per-request 创建一份，避免不同 chat 串扰
+ *    - signal:      调用方持有 AbortController，断开/超时时主动 abort
+ *
+ *  落盘策略：
+ *    用 try/finally 包住 runQuery；不管成功、抛错、还是被中断都保存当前
+ *    history。中断时 loop.ts 内部会先把"用户按下了 ESC/Ctrl+C"标记
+ *    消息追加到 history，所以落盘的也是合法且完整的会话状态。
+ * ============================================================
+ */
+
+import { loadContext, saveContext } from '../context/persistContext.js';
+import { acquireContextLock } from '../context/contextLock.js';
+import { startTurnJournal } from '../memory/turnJournal.js';
+import type { PluginEvent } from '../plugins/pluginApi.js';
+import { runWithPlugins } from '../plugins/pluginRunner.js';
+import type {
+  ImageDetail,
+  ImageInputSpec,
+  LoopEvent,
+  Message,
+  MessageAttachmentRef,
+  MessageBrowserReference,
+  Provider,
+} from '../types.js';
+import type { SessionState } from './sessionState.js';
+
+export interface RunTurnOptions {
+  userInput: string;
+  provider: Provider;
+  sessionFile: string;
+  systemPrompt?: string;
+  sessionState?: SessionState;
+  signal?: AbortSignal;
+  maxTurns?: number;
+  runtimeContext?: import('../runtime/agentRuntimeContext.js').AgentRuntimeContext;
+  allowedTools?: import('../loop.js').RunQueryOptions['allowedTools'];
+  /** DI：透传给 runWithPlugins→runQuery（仅测试用，生产不传走默认实现）。
+   *  让测试用显式注入替代 mock.module(loop.js)——后者会全局泄漏污染其它测试文件。 */
+  chat?: import('../plugins/pluginRunner.js').PluginRunnerOptions['chat'];
+  executeTool?: import('../plugins/pluginRunner.js').PluginRunnerOptions['executeTool'];
+  commitFormalDelivery?: import('../plugins/pluginRunner.js').PluginRunnerOptions['commitFormalDelivery'];
+  /** 工具执行闸门（生产用）：透传给 runWithPlugins→runQuery。见 src/toolGate.ts。 */
+  toolGate?: import('../plugins/pluginRunner.js').PluginRunnerOptions['toolGate'];
+  /** 只对本次模型回合可见，不写入 session。 */
+  transientContext?: import('../plugins/pluginRunner.js').PluginRunnerOptions['transientContext'];
+  transientBundle?: import('../plugins/pluginRunner.js').PluginRunnerOptions['transientBundle'];
+  promptCache?: import('../plugins/pluginRunner.js').PluginRunnerOptions['promptCache'];
+  userAttachments?: MessageAttachmentRef[];
+  /** Stable message identity supplied by a host/runtime request. */
+  userMessageId?: string;
+  userBrowserReferences?: MessageBrowserReference[];
+  imageInputs?: ImageInputSpec[];
+  parseInlineImages?: boolean;
+  imageDetail?: ImageDetail;
+  imageMaxLongSidePixel?: number;
+  browserRun?: import('../types.js').ToolCallContext['browserRun'];
+  computerRun?: import('../types.js').ToolCallContext['computerRun'];
+  computerIntervention?: import('../types.js').ToolCallContext['computerIntervention'];
+  memoryContext?: import('../loop.js').RunQueryOptions['memoryContext'];
+  /** Explicit history for an isolated, non-persistent turn. */
+  initialHistory?: Message[];
+  /** Defaults to true. False avoids reading, locking, or writing sessionFile. */
+  persist?: boolean;
+}
+
+/**
+ * 已有历史时，用调用方新算好的 systemPrompt（含当前日期/实时扫描的 skills·plugins 清单/
+ * 项目指令）替换旧的 system 消息，其余历史原样保留——与 ui/Root.tsx 的 TUI 启动逻辑、
+ * workflow-runner::refreshWorkflowSystemPrompt 行为一致。堵上 headless 会话（cron-runner
+ * 纯文本 action 等长期复用同一 sessionFile 的调用方）系统提示词只在首次开会话时生效、
+ * 此后永久冻结的口子——此前的行为是"已有历史就完全忽略新 systemPrompt"，日期/skills/
+ * plugins/项目指令都不会再刷新，与"运行时实时扫描"的设计承诺矛盾。
+ *
+ * 没有 loaded（全新会话）走原逻辑；调用方未传 systemPrompt 时不触碰已有历史（向后兼容）。
+ *
+ * ★ 提示词缓存不变量：调用方传进来的 systemPrompt **必须是稳定层**
+ *   （buildBaseSystemPrompt，不含日期/Advisor 状态/记忆召回）。否则这里每轮重写
+ *   history[0] 就会让 system 消息字节逐轮变化，provider 的前缀缓存从第一个 token
+ *   起全部失配 —— 本函数是 headless/cron/Desktop 路径上最隐蔽的一处缓存杀手。
+ *   易变内容改走 opts.transientContext（loop 只装饰当前用户消息的模型副本）。
+ *   稳定层是确定性的，所以这里的"每轮刷新"退化成逐字节相同的 no-op，
+ *   既保住了"运行时实时扫描"的承诺，又不破坏缓存。
+ */
+function buildInitialHistory(
+  loaded: Message[] | null,
+  systemPrompt: string | undefined,
+): Message[] {
+  if (!loaded) {
+    return systemPrompt ? [{ role: 'system', content: systemPrompt }] : [];
+  }
+  if (!systemPrompt) return loaded;
+  const rest = loaded[0]?.role === 'system' ? loaded.slice(1) : loaded;
+  return [{ role: 'system', content: systemPrompt }, ...rest];
+}
+
+export async function* runTurn(
+  opts: RunTurnOptions,
+): AsyncGenerator<LoopEvent | PluginEvent, void, void> {
+  const persist = opts.persist !== false;
+  const release = persist ? await acquireContextLock(opts.sessionFile, opts.signal) : async () => {};
+  const loaded = opts.initialHistory ?? (persist ? await loadContext(opts.sessionFile) : null);
+  const history: Message[] = buildInitialHistory(loaded, opts.systemPrompt);
+  const historyStart = history.length;
+  // 会话原文记账：实现在 src/memory/turnJournal.ts（TUI 的 useChat 用同一份），
+  // 刻意不下沉到 runQuery —— 子 Agent 与 workflow 步也调 runQuery，记在那里会把
+  // 子任务提示词当成"用户说的话"污染历史检索。
+  const journal = await startTurnJournal({
+    memoryContext: opts.memoryContext,
+    userInput: opts.userInput,
+    ...(opts.userMessageId ? { userMessageId: opts.userMessageId } : {}),
+  });
+
+  try {
+    yield* runWithPlugins(opts.userInput, {
+      provider: opts.provider,
+      history,
+      signal: opts.signal,
+      maxTurns: opts.maxTurns,
+      runtimeContext: opts.runtimeContext,
+      allowedTools: opts.allowedTools,
+      sessionState: opts.sessionState,
+      chat: opts.chat,
+      executeTool: opts.executeTool,
+      commitFormalDelivery: opts.commitFormalDelivery,
+      toolGate: opts.toolGate,
+      transientContext: opts.transientContext,
+      transientBundle: opts.transientBundle,
+      promptCache: opts.promptCache,
+      userAttachments: opts.userAttachments,
+      userMessageId: opts.userMessageId,
+      userBrowserReferences: opts.userBrowserReferences,
+      imageInputs: opts.imageInputs,
+      parseInlineImages: opts.parseInlineImages,
+      imageDetail: opts.imageDetail,
+      imageMaxLongSidePixel: opts.imageMaxLongSidePixel,
+      browserRun: opts.browserRun,
+      computerRun: opts.computerRun,
+      computerIntervention: opts.computerIntervention,
+      memoryContext: opts.memoryContext,
+    });
+  } finally {
+    try {
+      await journal?.finish(history, historyStart);
+      if (persist) await saveContext(history, opts.sessionFile);
+    } finally {
+      await release();
+    }
+  }
+}