minimal-agent 0.12.0 → 0.14.0

package/src/ui/hooks/useChat.ts

@@ -15,50 +15,79 @@
  * ============================================================
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { stat } from 'node:fs/promises';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
+import {
+  type AskAnswer,
+  type AskQuestionSpec,
+  type AskSource,
+  createAskCoordinator,
+  setAskHandler,
+} from '../../askBridge.js';
 import { getWorkingDir, setWorkingDir } from '../../bootstrap/workingDir.js';
+import type { ComputerUseCliMode } from '../../cli/computerUse.js';
+import {
+  createCliComputerRun,
+  createComputerUseHostGate,
+} from '../../cli/computerUse.js';
 import { forceCompact } from '../../context/compact.js';
+import { acquireContextLock } from '../../context/contextLock.js';
 import {
   clearContext,
   loadContext,
   saveContext,
 } from '../../context/persistContext.js';
 import { resetReactiveCompactState } from '../../context/reactiveCompact.js';
-import { acquireContextLock } from '../../context/contextLock.js';
-import { workspaceIndexService } from '../../context/workspaceIndex.js';
+import {
+  resolveSessionFile,
+  sessionFileFor,
+} from '../../context/sessionPath.js';
 import {
   getActiveSession,
+  listSessionSummaries,
   setActiveSession,
   updateSessionMetadata,
 } from '../../context/sessionRegistry.js';
+import { workspaceIndexService } from '../../context/workspaceIndex.js';
 import {
-  resolveSessionFile,
-  sessionFileFor,
-} from '../../context/sessionPath.js';
-import { runQuery } from '../../loop.js';
-import { buildBaseSystemPrompt, buildTransientPromptBundle } from '../../prompts/system.js';
+  HumanInterventionCoordinator,
+  type PendingHumanIntervention,
+} from '../../humanIntervention.js';
 import { createPromptCacheContext } from '../../llm/promptCache.js';
+import { runQuery } from '../../loop.js';
+import {
+  type TurnJournal,
+  startTurnJournal,
+} from '../../memory/turnJournal.js';
+import { createInputQueue } from '../../messageQueue.js';
+import type { PluginEvent } from '../../plugins/pluginApi.js';
+import { runWithPlugins } from '../../plugins/pluginRunner.js';
+import {
+  buildBaseSystemPrompt,
+  buildTransientPromptBundle,
+} from '../../prompts/system.js';
+import {
+  refreshStableSystemPrompt,
+  upsertStableSystemMessage,
+} from '../../prompts/stableSystemPrompt.js';
 import {
   createAgentRuntimeContext,
   filterToolsForRuntime,
   memoryContextFromRuntime,
 } from '../../runtime/agentRuntimeContext.js';
-import { startTurnJournal, type TurnJournal } from '../../memory/turnJournal.js';
-import { ALL_TOOLS, getToolByName } from '../../tools/index.js';
-import { createInputQueue } from '../../messageQueue.js';
 import {
-  createAskCoordinator,
-  setAskHandler,
-  type AskAnswer,
-  type AskQuestionSpec,
-  type AskSource,
-} from '../../askBridge.js';
-import { createAskSlot } from './askSlot.js';
-import { figures } from '../figures.js';
+  getOrCreateSessionState,
+  sessionStateKey,
+} from '../../session/sessionState.js';
+import { filterToolsForCategories } from '../../team/toolPolicy.js';
+import { runAdvisor } from '../../tools/advisor/advisor.js';
+import { classifyComputerAutomationIntent } from '../../tools/computeruse/computerIntent.js';
+import { computerUseService } from '../../tools/computeruse/computerUseService.js';
+import { createComputerInterventionAdapter } from '../../tools/computeruse/intervention.js';
+import type { ComputerUseRunContext } from '../../tools/computeruse/protocol.js';
+import { ALL_TOOLS, getToolByName } from '../../tools/index.js';
 import { clearFileState } from '../../tools/shared/fileState.js';
-import { getOrCreateSessionState, sessionStateKey } from '../../session/sessionState.js';
 import { hydrateSessionWorktree } from '../../tools/worktree/sessionWorktree.js';
 import type {
   LoopEvent,
@@ -68,23 +97,8 @@ import type {
   ToolResult,
   ToolStatusState,
 } from '../../types.js';
-import { runAdvisor } from '../../tools/advisor/advisor.js';
-import type { PluginEvent } from '../../plugins/pluginApi.js';
-import { runWithPlugins } from '../../plugins/pluginRunner.js';
 import { dlog } from '../../utils/debugLog.js';
-import type { ComputerUseCliMode } from '../../cli/computerUse.js';
-import { createCliComputerRun, createComputerUseHostGate } from '../../cli/computerUse.js';
-import {
-  computerUseService,
-} from '../../tools/computeruse/computerUseService.js';
-import {
-  HumanInterventionCoordinator,
-  type PendingHumanIntervention,
-} from '../../humanIntervention.js';
-import { createComputerInterventionAdapter } from '../../tools/computeruse/intervention.js';
-import type {
-  ComputerUseRunContext,
-} from '../../tools/computeruse/protocol.js';
+import { createAskSlot } from './askSlot.js';
 
 export interface PluginProgressState {
   pluginId: string;
@@ -95,7 +109,10 @@ export interface PluginProgressState {
 }
 
 /** loop.ts 每轮 yield 的 context_usage 事件（去掉 type 字段）。 */
-export type ContextUsageInfo = Omit<Extract<LoopEvent, { type: 'context_usage' }>, 'type'>;
+export type ContextUsageInfo = Omit<
+  Extract<LoopEvent, { type: 'context_usage' }>,
+  'type'
+>;
 
 export interface UseChatResult {
   history: Message[];
@@ -285,7 +302,10 @@ function useThrottledFlush({
   const append = useCallback(
     (delta: string) => {
       bufferRef.current += delta;
-      if (typeof maxChars === 'number' && bufferRef.current.length >= maxChars) {
+      if (
+        typeof maxChars === 'number' &&
+        bufferRef.current.length >= maxChars
+      ) {
         flush();
         return;
       }
@@ -322,21 +342,11 @@ export function useChat(args: {
   const [transientError, setTransientError] = useState<string | null>(null);
   const [interrupted, setInterrupted] = useState(false);
 
-  /**
-   * 暂态错误状态机的跨事件可变上下文（用 ref，不需要为它单独重渲染）。
-   *   - activeStepId：当前正在执行的 workflow step id（workflow_step_start 记下，
-   *     该 step 的 workflow_step_end 清除）；null = 不在任何 step 内。
-   *   - pendingLlmError：该 step 执行中捕获到的最近一次 llm_error 文案（暂存，
-   *     等 step 结束才决定丢弃 or 提升为永久红字）。
-   * handleEvent 通过 setters.workflowCtx 同步读写这个对象（pure 逻辑，测试可注入 stub）。
-   */
-  const workflowCtxRef = useRef<{
-    activeStepId: string | null;
-    pendingLlmError: string | null;
-  }>({ activeStepId: null, pendingLlmError: null });
-  // 工作流步骤 id → 人话进度名（title）映射：start 记入、end/skipped 回查，
-  // 让 scrollback 三种进度行（▶/✓/⊘）都显示同一人话名而非 id。跨事件持 ref。
-  const stepTitlesRef = useRef<Map<string, string>>(new Map());
+  // 注：这里曾有 workflowCtxRef（activeStepId / pendingLlmError）与 stepTitlesRef，
+  // 服务于 yaml DSL 的 workflow_step_* 事件。那些事件随引擎删除后没有任何发送方，
+  // 于是 activeStepId 恒为 null、两条依赖它的暂态错误分支永远走不到 —— 一并删掉。
+  // 代码编排引擎把 llm_error / max_turns 在 api.ts 内部消化（不外泄给顶层），
+  // 不需要宿主再做这层「暂态还是永久」的裁决。
   const [pluginProgress, setPluginProgress] =
     useState<PluginProgressState | null>(null);
 
@@ -350,22 +360,31 @@ export function useChat(args: {
    * 比 useTokenUsage 的本地估算更准；未收到过（如刚启动、纯只读问答走了只读快速
    * 路径）时该值仍是 null，StatusLine 降级回 useTokenUsage 估算。
    */
-  const [contextUsage, setContextUsage] = useState<ContextUsageInfo | null>(null);
+  const [contextUsage, setContextUsage] = useState<ContextUsageInfo | null>(
+    null,
+  );
   const [computerUseMode, setComputerUseMode] =
     useState<ComputerUseCliMode>('disabled');
   const promptToolSignatureRef = useRef('');
   const activeComputerRunRef = useRef<ComputerUseRunContext | null>(null);
-  const [computerInterventions] = useState(() => new HumanInterventionCoordinator());
+  const [computerInterventions] = useState(
+    () => new HumanInterventionCoordinator(),
+  );
   const [pendingComputerIntervention, setPendingComputerIntervention] =
     useState<PendingHumanIntervention | null>(null);
-  useEffect(() => computerInterventions.subscribe((event) => {
-    if (event.type === 'started') {
-      setPendingComputerIntervention(event.intervention);
-    } else {
-      setPendingComputerIntervention((current) =>
-        current?.id === event.resolution.intervention.id ? null : current);
-    }
-  }), [computerInterventions]);
+  useEffect(
+    () =>
+      computerInterventions.subscribe((event) => {
+        if (event.type === 'started') {
+          setPendingComputerIntervention(event.intervention);
+        } else {
+          setPendingComputerIntervention((current) =>
+            current?.id === event.resolution.intervention.id ? null : current,
+          );
+        }
+      }),
+    [computerInterventions],
+  );
   /**
    * 工具并行执行：以 callId 为 key 保存所有运行中工具。
    * 用 Map 是为了 O(1) 增删；对外 memo 物化成稳定数组（Map 迭代顺序 = 插入顺序，
@@ -382,8 +401,12 @@ export function useChat(args: {
 
   const [inputQueue] = useState(() => createInputQueue());
   const [queuedCount, setQueuedCount] = useState(0);
-  const [queuedItems, setQueuedItems] = useState<readonly import('../../messageQueue.js').QueuedInput[]>([]);
-  const runningToolsRef = useRef<Map<string, { toolName: string; isCancelable: boolean }>>(new Map());
+  const [queuedItems, setQueuedItems] = useState<
+    readonly import('../../messageQueue.js').QueuedInput[]
+  >([]);
+  const runningToolsRef = useRef<
+    Map<string, { toolName: string; isCancelable: boolean }>
+  >(new Map());
 
   useEffect(() => {
     return inputQueue.subscribe(() => {
@@ -398,12 +421,14 @@ export function useChat(args: {
   // askSlot.ts（纯函数可单测）；这里只桥接 React 状态。
   const [pendingAsk, setPendingAsk] = useState<AskQuestionSpec[] | null>(null);
   // 提问来源：子任务提问时 kind:'subagent' + description → AskQuestion 显示徽标。
-  const [pendingAskSource, setPendingAskSource] = useState<AskSource | null>(null);
+  const [pendingAskSource, setPendingAskSource] = useState<AskSource | null>(
+    null,
+  );
   const [pendingAskQueueCount, setPendingAskQueueCount] = useState(0);
   const [askSlot] = useState(() =>
     createAskSlot((questions, source) => {
       setPendingAsk(questions);
-      setPendingAskSource(questions ? source ?? null : null);
+      setPendingAskSource(questions ? (source ?? null) : null);
     }),
   );
 
@@ -456,7 +481,6 @@ export function useChat(args: {
     setRunningToolsMap(new Map());
     // 暂态错误是"过程级"提示，turn 结束 / 切换时一并清掉，不残留到下一轮
     setTransientError(null);
-    workflowCtxRef.current = { activeStepId: null, pendingLlmError: null };
   }, []);
 
   /** turn 结束 / 中断 / 切换时一并取消所有节流 buffer 的 pending timer。 */
@@ -492,9 +516,11 @@ export function useChat(args: {
   // 归属校验保证已答完提问的 abort 监听器不会清掉后来提问的槽，否则后者 promise
   // 永不落定 → 整轮死挂，见 askSlot.ts 头注）。
   useEffect(() => {
-    setAskHandler(createAskCoordinator(askSlot.handler, (status) => {
-      setPendingAskQueueCount(status.queuedCount ?? 0);
-    }));
+    setAskHandler(
+      createAskCoordinator(askSlot.handler, (status) => {
+        setPendingAskQueueCount(status.queuedCount ?? 0);
+      }),
+    );
     return () => setAskHandler(null);
   }, [askSlot]);
 
@@ -549,37 +575,46 @@ export function useChat(args: {
   const runManualAdvisor = useCallback(
     async (note?: string): Promise<ToolResult> => {
       if (isLoading) {
-        return { ok: false, error: '当前有任务在执行；等它结束或按 ESC 中断后再咨询顾问。' };
+        return {
+          ok: false,
+          error: '当前有任务在执行；等它结束或按 ESC 中断后再咨询顾问。',
+        };
       }
       const callId = 'manual-advisor';
       const ac = new AbortController();
       abortRef.current = ac;
       setIsLoading(true);
       setProgressStage('tool_executing');
-      setRunningToolsMap(new Map([[callId, {
-        toolName: 'Advisor',
-        argsPreview: note ?? '',
-        status: 'running' as const,
-        argsFriendly: '正在咨询顾问模型',
-      }]]));
+      setRunningToolsMap(
+        new Map([
+          [
+            callId,
+            {
+              toolName: 'Advisor',
+              argsPreview: note ?? '',
+              status: 'running' as const,
+              argsFriendly: '正在咨询顾问模型',
+            },
+          ],
+        ]),
+      );
       try {
-        return await runAdvisor(
-          note ? { note } : {},
-          ac.signal,
-          {
-            history: historyRef.current,
-            advisorCalls: { used: 0, max: 1 },
-            advisorInvocation: 'manual',
-            reportProgress: (message) => {
-              // advisor.ts 侧已有 200ms 节流，这里直接落状态即可。
-              setRunningToolsMap((prev) => {
-                const current = prev.get(callId);
-                if (!current) return prev;
-                return new Map(prev).set(callId, { ...current, progress: message });
+        return await runAdvisor(note ? { note } : {}, ac.signal, {
+          history: historyRef.current,
+          advisorCalls: { used: 0, max: 1 },
+          advisorInvocation: 'manual',
+          reportProgress: (message) => {
+            // advisor.ts 侧已有 200ms 节流，这里直接落状态即可。
+            setRunningToolsMap((prev) => {
+              const current = prev.get(callId);
+              if (!current) return prev;
+              return new Map(prev).set(callId, {
+                ...current,
+                progress: message,
               });
-            },
+            });
           },
-        );
+        });
       } finally {
         setIsLoading(false);
         setProgressStage('idle');
@@ -590,7 +625,10 @@ export function useChat(args: {
         // （见下方 consumeQueued）—— 手动咨询不走那条路径，排队的话就会静静躺着，
         // 用户看到「排队 1 条」却永远不执行，直到下次提交才错序跑掉。
         const queued = inputQueue.dequeue();
-        if (queued) queueMicrotask(() => { void submitRef.current?.(queued.value); });
+        if (queued)
+          queueMicrotask(() => {
+            void submitRef.current?.(queued.value);
+          });
       }
     },
     [isLoading, inputQueue],
@@ -604,7 +642,8 @@ export function useChat(args: {
       if (isLoading) {
         inputQueue.enqueue(trimmed, 'next');
         const running = Array.from(runningToolsRef.current.values());
-        const allCancelable = running.length > 0 && running.every(t => t.isCancelable);
+        const allCancelable =
+          running.length > 0 && running.every((t) => t.isCancelable);
         if (allCancelable) {
           abortRef.current?.abort('interrupt');
         }
@@ -623,8 +662,6 @@ export function useChat(args: {
       setProgressStage('idle');
       setReasoningPreview('');
       setRunningToolsMap(new Map());
-      // 重置暂态错误状态机（防上一轮工作流残留）
-      workflowCtxRef.current = { activeStepId: null, pendingLlmError: null };
 
       const ac = new AbortController();
       abortRef.current = ac;
@@ -641,20 +678,31 @@ export function useChat(args: {
       }, 10_000);
 
       try {
-        await updateSessionMetadata(getWorkingDir(), activeSessionIdRef.current, {
-          lastMessagePreview: trimmed,
-        }).catch(() => {});
-        const activeFile = sessionFileFor(getWorkingDir(), activeSessionIdRef.current);
+        await updateSessionMetadata(
+          getWorkingDir(),
+          activeSessionIdRef.current,
+          {
+            lastMessagePreview: trimmed,
+          },
+        ).catch(() => {});
+        const activeFile = sessionFileFor(
+          getWorkingDir(),
+          activeSessionIdRef.current,
+        );
         releaseContextLock = await acquireContextLock(activeFile, ac.signal);
         // Gateway/Cron may have written this cwd since the TUI rendered its last frame.
         // Reload after acquiring the cross-process lock so this turn extends the newest history.
         const latest = await loadContext(activeFile);
         if (latest) {
-          const ephemeral = historyRef.current.filter((message) => message.role === 'system' && message._ephemeral);
+          const ephemeral = historyRef.current.filter(
+            (message) => message.role === 'system' && message._ephemeral,
+          );
           historyRef.current.length = 0;
           historyRef.current.push(...latest, ...ephemeral);
         }
-        const workspace = await workspaceIndexService.findByPath(getWorkingDir()).catch(() => null);
+        const workspace = await workspaceIndexService
+          .findByPath(getWorkingDir())
+          .catch(() => null);
         const computerRun =
           computerUseMode !== 'disabled'
             ? createCliComputerRun({
@@ -684,17 +732,25 @@ export function useChat(args: {
               },
             })
           : undefined;
-        const toolGate = computerRun ? createComputerUseHostGate(computerRun) : undefined;
-        const turnSessionState = getOrCreateSessionState(sessionStateKey({
-          surface: 'tui', workspaceId: workspace?.id,
-          cwd: workspace?.id ? undefined : getWorkingDir(),
-          sessionId: activeSessionIdRef.current,
-        }));
+        const toolGate = computerRun
+          ? createComputerUseHostGate(computerRun)
+          : undefined;
+        const turnSessionState = getOrCreateSessionState(
+          sessionStateKey({
+            surface: 'tui',
+            workspaceId: workspace?.id,
+            cwd: workspace?.id ? undefined : getWorkingDir(),
+            sessionId: activeSessionIdRef.current,
+          }),
+        );
         await hydrateSessionWorktree({
-          sessionState: turnSessionState, workspaceId: workspace?.id,
-          sessionId: activeSessionIdRef.current, cwd: getWorkingDir(),
+          sessionState: turnSessionState,
+          workspaceId: workspace?.id,
+          sessionId: activeSessionIdRef.current,
+          cwd: getWorkingDir(),
         });
-        const effectiveCwd = turnSessionState.activeWorktree?.path ?? getWorkingDir();
+        const effectiveCwd =
+          turnSessionState.activeWorktree?.path ?? getWorkingDir();
         const runtimeContext = createAgentRuntimeContext({
           surface: 'tui',
           profile: 'main',
@@ -705,18 +761,54 @@ export function useChat(args: {
           memoryAccess: 'read-write',
           interactiveAsk: true,
           computer: computerRun,
+          computerIntent: classifyComputerAutomationIntent(
+            trimmed,
+            turnSessionState.computerAutomation,
+          ),
           computerIntervention,
           toolGate,
         });
-        const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
+        const runtimeTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
+        const sessionSummary = (
+          await listSessionSummaries(getWorkingDir())
+        ).find((session) => session.id === activeSessionIdRef.current);
+        const currentProvider = providerRef.current;
+        const effectiveGatewayCategories =
+          currentProvider.source === 'gateway'
+            ? [
+                ...new Set(
+                  (
+                    sessionSummary?.onlineToolCategories ??
+                    currentProvider.gatewayDefaultToolCategories ??
+                    currentProvider.gatewayMaxToolCategories ??
+                    []
+                  ).filter(
+                    (category) =>
+                      currentProvider.gatewayMaxToolCategories?.includes(
+                        category,
+                      ) ?? true,
+                  ),
+                ),
+              ]
+            : undefined;
+        const turnProvider =
+          currentProvider.source === 'gateway'
+            ? {
+                ...currentProvider,
+                gatewayToolCategories: effectiveGatewayCategories,
+              }
+            : currentProvider;
+        const turnTools =
+          currentProvider.source === 'gateway'
+            ? filterToolsForCategories(runtimeTools, effectiveGatewayCategories)
+            : runtimeTools;
         const toolSignature = `${effectiveCwd}\0${turnTools.map((tool) => tool.name).join(',')}`;
         if (promptToolSignatureRef.current !== toolSignature) {
-          const stablePrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
-          const rest = historyRef.current[0]?.role === 'system'
-            ? historyRef.current.slice(1)
-            : [...historyRef.current];
-          historyRef.current.length = 0;
-          historyRef.current.push({ role: 'system', content: stablePrompt }, ...rest);
+          await refreshStableSystemPrompt(
+            historyRef.current,
+            effectiveCwd,
+            turnTools,
+          );
           promptToolSignatureRef.current = toolSignature;
         }
         // 每回合只刷新易变层；稳定层仅在实际能力目录变化时重建。
@@ -742,11 +834,12 @@ export function useChat(args: {
           userInput: trimmed,
         }).catch(() => null);
         for await (const ev of runWithPlugins(trimmed, {
-          provider: providerRef.current,
+          provider: turnProvider,
           history: historyRef.current,
           signal: ac.signal,
           runtimeContext,
           allowedTools: turnTools.map((tool) => tool.name),
+          availableTools: turnTools,
           sessionState: turnSessionState,
           parseInlineImages: true,
           ...(turnTransient ? { transientBundle: turnTransient } : {}),
@@ -781,9 +874,6 @@ export function useChat(args: {
             setContextUsage,
             // 暂态错误（工作流步内 llm_error / 重试进度）→ LiveArea 黄字
             setTransientError,
-            workflowCtx: workflowCtxRef.current,
-            // 步骤 id→人话名映射：scrollback 进度行三态（▶/✓/⊘）统一显示 title
-            stepTitles: stepTitlesRef.current,
             // 节流相关 —— buffer 累积 + 100ms timer flush
             appendStreamingDelta: streamingFlush.append,
             flushStreamingBuffer: streamingFlush.flush,
@@ -816,11 +906,16 @@ export function useChat(args: {
         activeComputerRunRef.current = null;
         runningToolsRef.current.clear();
         // 记账失败不影响落盘与解锁（它是附加能力，不是功能）。
-        await turnJournal?.finish(historyRef.current, turnJournalStart).catch(() => undefined);
+        await turnJournal
+          ?.finish(historyRef.current, turnJournalStart)
+          .catch(() => undefined);
         turnJournal = null;
         // v2 multi-session：持久化到当前 active session 文件。
         try {
-          await saveContext(historyRef.current, sessionFileFor(getWorkingDir(), activeSessionIdRef.current));
+          await saveContext(
+            historyRef.current,
+            sessionFileFor(getWorkingDir(), activeSessionIdRef.current),
+          );
         } finally {
           await releaseContextLock?.();
         }
@@ -838,7 +933,6 @@ export function useChat(args: {
     [
       bump,
       isLoading,
-      sessionFile,
       streamingFlush,
       cancelAllThrottles,
       reasoningFlush,
@@ -867,9 +961,12 @@ export function useChat(args: {
   const stopComputerUse = useCallback(async (): Promise<string> => {
     setComputerUseMode('disabled');
     const context = activeComputerRunRef.current;
-    if (!context) return '已撤销后续回合授权；当前没有正在运行的 Computer Use。';
+    if (!context)
+      return '已撤销后续回合授权；当前没有正在运行的 Computer Use。';
     computerInterventions.abort(context);
-    const response = await computerUseService.request(context, { action: 'stop' });
+    const response = await computerUseService.request(context, {
+      action: 'stop',
+    });
     return response.ok
       ? '已停止当前回合的 Computer Use，并撤销后续回合授权。'
       : `已撤销后续回合授权；原生停止失败：${response.error?.message ?? '未知错误'}`;
@@ -946,7 +1043,10 @@ export function useChat(args: {
 
     // 生成全新的 system prompt（实时扫 skills + 拼项目指令），
     // 与启动时 main.tsx buildInitialHistory 行为完全一致
-    const newSystemPrompt = await buildBaseSystemPrompt(getWorkingDir(), ALL_TOOLS);
+    const newSystemPrompt = await buildBaseSystemPrompt(
+      getWorkingDir(),
+      ALL_TOOLS,
+    );
     historyRef.current.length = 0;
     historyRef.current.push({ role: 'system', content: newSystemPrompt });
     promptToolSignatureRef.current = '';
@@ -966,13 +1066,19 @@ export function useChat(args: {
     // 清空磁盘上的持久化文件（防止下次启动又加载损坏数据）
     await clearContext();
     // 清空 pre-read guard 状态表（防止跨 session 的 Read 记录污染新会话）
-    const workspace = await workspaceIndexService.findByPath(getWorkingDir()).catch(() => null);
-    clearFileState(getOrCreateSessionState(sessionStateKey({
-      surface: 'tui',
-      workspaceId: workspace?.id,
-      cwd: workspace?.id ? undefined : getWorkingDir(),
-      sessionId: activeSessionIdRef.current,
-    })).fileReads);
+    const workspace = await workspaceIndexService
+      .findByPath(getWorkingDir())
+      .catch(() => null);
+    clearFileState(
+      getOrCreateSessionState(
+        sessionStateKey({
+          surface: 'tui',
+          workspaceId: workspace?.id,
+          cwd: workspace?.id ? undefined : getWorkingDir(),
+          sessionId: activeSessionIdRef.current,
+        }),
+      ).fileReads,
+    );
     // 刚清空，不需要再保存一次"空历史"
   }, [bump, isLoading, cancelAllThrottles, resetTurnState]);
 
@@ -993,7 +1099,9 @@ export function useChat(args: {
     let success = false;
     try {
       const cwd = getWorkingDir();
-      const workspace = await workspaceIndexService.findByPath(cwd).catch(() => null);
+      const workspace = await workspaceIndexService
+        .findByPath(cwd)
+        .catch(() => null);
       const r = await forceCompact(
         historyRef.current,
         args.provider,
@@ -1056,7 +1164,10 @@ export function useChat(args: {
 
       // 1. 保住当前 session
       try {
-        await saveContext(historyRef.current, sessionFileFor(cwd, activeSessionIdRef.current));
+        await saveContext(
+          historyRef.current,
+          sessionFileFor(cwd, activeSessionIdRef.current),
+        );
       } catch {
         // 保存失败不阻塞切换（用户可能就是想切走止损）
       }
@@ -1102,80 +1213,104 @@ export function useChat(args: {
     [bump, isLoading, cancelAllThrottles, resetTurnState],
   );
 
-  const switchWorkspace = useCallback(async (cwd: string, sessionId: string) => {
-    if (isLoading) return false;
-    const targetCwd = cwd.trim();
-    const targetSessionId = sessionId.trim();
-    if (!targetCwd || !targetSessionId) return false;
+  const switchWorkspace = useCallback(
+    async (cwd: string, sessionId: string) => {
+      if (isLoading) return false;
+      const targetCwd = cwd.trim();
+      const targetSessionId = sessionId.trim();
+      if (!targetCwd || !targetSessionId) return false;
 
-    let loaded: Message[] | null = null;
-    let targetExists = false;
-    try {
-      const targetFile = await resolveSessionFile(targetCwd, targetSessionId);
-      try { targetExists = (await stat(targetFile)).isFile(); } catch { targetExists = false; }
-      loaded = await loadContext(targetFile);
-      if (targetExists && loaded === null) throw new Error('目标会话历史损坏或无法读取');
-    } catch (error) {
-      setError(error instanceof Error ? error.message : String(error));
-      bump();
-      return false;
-    }
-
-    let systemPrompt: string;
-    try { systemPrompt = await buildBaseSystemPrompt(targetCwd, ALL_TOOLS); }
-    catch (error) {
-      setError(`无法打开工作区：${error instanceof Error ? error.message : String(error)}`);
-      bump();
-      return false;
-    }
+      let loaded: Message[] | null = null;
+      let targetExists = false;
+      try {
+        const targetFile = await resolveSessionFile(targetCwd, targetSessionId);
+        try {
+          targetExists = (await stat(targetFile)).isFile();
+        } catch {
+          targetExists = false;
+        }
+        loaded = await loadContext(targetFile);
+        if (targetExists && loaded === null)
+          throw new Error('目标会话历史损坏或无法读取');
+      } catch (error) {
+        setError(error instanceof Error ? error.message : String(error));
+        bump();
+        return false;
+      }
 
-    const previousCwd = getWorkingDir();
-    try {
-      await saveContext(historyRef.current, sessionFileFor(previousCwd, activeSessionIdRef.current));
-    } catch {
-      // A damaged old workspace must not trap the user in it.
-    }
+      let systemPrompt: string;
+      try {
+        systemPrompt = await buildBaseSystemPrompt(targetCwd, ALL_TOOLS);
+      } catch (error) {
+        setError(
+          `无法打开工作区：${error instanceof Error ? error.message : String(error)}`,
+        );
+        bump();
+        return false;
+      }
 
-    try { await setActiveSession(targetCwd, targetSessionId); }
-    catch (error) {
-      setError(`无法切换 Session：${error instanceof Error ? error.message : String(error)}`);
-      bump();
-      return false;
-    }
-    setWorkingDir(targetCwd);
-    activeSessionIdRef.current = targetSessionId;
-    setActiveSessionId(targetSessionId);
+      const previousCwd = getWorkingDir();
+      try {
+        await saveContext(
+          historyRef.current,
+          sessionFileFor(previousCwd, activeSessionIdRef.current),
+        );
+      } catch {
+        // A damaged old workspace must not trap the user in it.
+      }
 
-    historyRef.current.length = 0;
-    historyRef.current.push({ role: 'system', content: systemPrompt });
-    promptToolSignatureRef.current = '';
-    if (loaded?.length) {
-      historyRef.current.push(...(loaded[0]?.role === 'system' ? loaded.slice(1) : loaded));
-    }
+      try {
+        await setActiveSession(targetCwd, targetSessionId);
+      } catch (error) {
+        setError(
+          `无法切换 Session：${error instanceof Error ? error.message : String(error)}`,
+        );
+        bump();
+        return false;
+      }
+      setWorkingDir(targetCwd);
+      activeSessionIdRef.current = targetSessionId;
+      setActiveSessionId(targetSessionId);
 
-    const targetWorkspace = await workspaceIndexService.findByPath(targetCwd).catch(() => null);
-    clearFileState(getOrCreateSessionState(sessionStateKey({
-      surface: 'tui',
-      workspaceId: targetWorkspace?.id,
-      cwd: targetWorkspace?.id ? undefined : targetCwd,
-      sessionId: targetSessionId,
-    })).fileReads);
-    resetReactiveCompactState();
-    cancelAllThrottles();
-    setContextUsage(null);
-    setError(null);
-    setInterrupted(false);
-    resetTurnState();
-    setCompactGeneration((generation) => generation + 1);
-    bump();
-    return true;
-  }, [bump, isLoading, cancelAllThrottles, resetTurnState]);
+      historyRef.current.length = 0;
+      historyRef.current.push(...(loaded ?? []));
+      upsertStableSystemMessage(historyRef.current, systemPrompt);
+      promptToolSignatureRef.current = '';
+
+      const targetWorkspace = await workspaceIndexService
+        .findByPath(targetCwd)
+        .catch(() => null);
+      clearFileState(
+        getOrCreateSessionState(
+          sessionStateKey({
+            surface: 'tui',
+            workspaceId: targetWorkspace?.id,
+            cwd: targetWorkspace?.id ? undefined : targetCwd,
+            sessionId: targetSessionId,
+          }),
+        ).fileReads,
+      );
+      resetReactiveCompactState();
+      cancelAllThrottles();
+      setContextUsage(null);
+      setError(null);
+      setInterrupted(false);
+      resetTurnState();
+      setCompactGeneration((generation) => generation + 1);
+      bump();
+      return true;
+    },
+    [bump, isLoading, cancelAllThrottles, resetTurnState],
+  );
 
   // history 用 useMemo 托管：version 变化时返回 historyRef.current 的浅拷贝。
   // 为什么必须 .slice()：runQuery 内部 mutate 同一个数组（push 新消息），如果这里
   // 返回同一引用，Ink <Static items={history}> 浅比较看不到 prop 变化 → 不 commit
   // 新增 message → turn 结束 LiveArea 消失后屏幕空白，看起来像"输出被吃掉"。
   // slice 后元素引用不变，只是数组容器是新的，足够让 Static 检测到 length 增长并 commit。
+  // version is an explicit invalidation counter; the callback intentionally
+  // reads the ref-backed history rather than the counter itself.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: version intentionally invalidates the ref-backed history snapshot
   const history = useMemo(() => historyRef.current.slice(), [version]);
 
   return {
@@ -1235,7 +1370,9 @@ export interface HandleEventSetters {
   setProgressStage: (s: ProgressStage) => void;
   setReasoningPreview: (updater: (prev: string) => string) => void;
   setRunningToolsMap: (
-    updater: (prev: Map<string, ToolStatusState>) => Map<string, ToolStatusState>,
+    updater: (
+      prev: Map<string, ToolStatusState>,
+    ) => Map<string, ToolStatusState>,
   ) => void;
   /**
    * 内核 context_usage 事件的落地 setter（可选——不传时该事件被静默忽略，
@@ -1255,122 +1392,31 @@ export interface HandleEventSetters {
   cancelToolBump: () => void;
   bump: () => void;
   /**
-   * 把一行工作流进度作为持久暗色行落进 scrollback（复用 ephemeralLine）。
-   * 让 /workflow 执行过程在 TUI 里逐步可见、且出错后仍停留在屏幕上——用户一眼看出停在哪步。
-   * 可选：非工作流场景（测试 / -p）不传也不影响。
+   * 把一行插件进度作为持久暗色行落进 scrollback（复用 ephemeralLine）。
+   *
+   * 状态行是**覆盖刷新**的，只留得住最后一条；而工作流排障总发生在跑完之后
+   * （「它停在哪一步了？」）。这条通道把每条进度也留在 scrollback 里，
+   * 失败后仍看得见。走 ephemeral 行：只进展示，不进 history、不被持久化。
+   * 可选：不传即关闭该行为（测试 / -p 不需要）。
    */
   emitProgressLine?: (text: string) => void;
   /**
    * 暂态错误 setter（喂 LiveArea 黄字，可被覆盖刷新）。
-   * 可选：不传时退化为"工作流步内 llm_error 不再永久红字残留 + 重试聚合"特性关闭，
-   *       非工作流路径行为完全不变（既有单测不传也不受影响）。
+   * 当前用于压缩失败提示与插件重试进度；可选，不传即关闭。
    */
   setTransientError?: (e: string | null) => void;
-  /**
-   * 暂态错误状态机的跨事件可变上下文（由 useChat 持 ref 注入）。
-   *   - activeStepId：当前正在执行的 workflow step id（null = 不在任何 step 内）
-   *   - pendingLlmError：该 step 内捕获的最近一次 llm_error 文案（暂存待裁决）
-   * handleEvent 同步读写它；可选——不传时降级（同 setTransientError 缺省）。
-   */
-  workflowCtx?: { activeStepId: string | null; pendingLlmError: string | null };
-  /**
-   * 工作流步骤 id → 已插值人话进度名（title）的映射（由 useChat 持 ref 注入）。
-   * workflow_step_start 带 title 时记入，step_end / step_skipped 据 id 回查，
-   * 让 scrollback 的 ▶/✓/✗/⊘ 三种进度行都显示同一个人话名而非 id + 块内序号。
-   * 可选——不传时退化为「end/skipped 显示 id」（既有单测不传也不受影响）。
-   */
-  stepTitles?: Map<string, string>;
 }
 
 export function handleEvent(
   ev: LoopEvent | PluginEvent,
   setters: HandleEventSetters,
 ): void {
-  // ---- 工作流进度事件（WorkflowEvent，不在 LoopEvent union 里）----
-  // 渲染成持久的暗色行落进 scrollback：跑到哪一步、成功/失败/跳过都看得见，
-  // 且出错后仍停留在屏幕上 —— 解决"工作流执行过程不可见、不知道停在哪"。
-  const wf = ev as {
-    type: string;
-    id?: string;
-    kind?: string;
-    index?: number;
-    total?: number;
-    ok?: boolean;
-    error?: string;
-    reason?: string;
-    name?: string;
-    totalSteps?: number;
-    title?: string;
-  };
-  // 据 id 回查人话进度名：声明了 title 的步走 title，否则回落 id（end/skipped 用）。
-  const titleOrId = (id: string | undefined): string =>
-    (id && setters.stepTitles?.get(id)) || id || '?';
-  switch (wf.type) {
-    case 'workflow_start':
-      setters.emitProgressLine?.(`${figures.step} 工作流 ${wf.name} 开始（共 ${wf.totalSteps} 步）`);
-      // 新工作流开始：清空上一条工作流残留的 title 映射，避免同名步串味。
-      setters.stepTitles?.clear();
-      // 工作流开始：立即刷新 token（可能已积累大量前置对话上下文）
-      setters.bump();
-      return;
-    case 'workflow_step_start':
-      // 声明了 title 的步显示人话名（与状态行一致、不显示块内相对序号——嵌套块
-      // 的 i/total 拼在一起会被误读成"跳步"）；未声明 title 的步保持 legacy 格式。
-      // ⎿ 前缀：step 行挂在「▶ 工作流 x 开始」下的层次连接符（figures.elbow 语汇，
-      // 与工具结果/蜂群树统一）。ephemeral 是尾部追加消息，不触任何既有前缀字节。
-      if (wf.title) {
-        if (wf.id) setters.stepTitles?.set(wf.id, wf.title);
-        setters.emitProgressLine?.(`  ${figures.elbow} ${figures.step} ${wf.title}`);
-      } else {
-        setters.emitProgressLine?.(
-          `  ${figures.elbow} ${figures.step} ${(wf.index ?? 0) + 1}/${wf.total ?? '?'} ${wf.id} (${wf.kind})`,
-        );
-      }
-      // 暂态错误状态机：记下当前正在执行的 step id，进入"该步内的 llm_error 暂态化"窗口。
-      // 进新步先清掉上一步可能残留的暂态错误（上一步已 end、不应跨步显示）。
-      if (setters.workflowCtx) {
-        setters.workflowCtx.activeStepId = wf.id ?? null;
-        setters.workflowCtx.pendingLlmError = null;
-      }
-      setters.setTransientError?.(null);
-      return;
-    case 'workflow_step_end':
-      setters.emitProgressLine?.(
-        `  ${figures.elbow} ${wf.ok ? figures.ok : figures.fail} ${titleOrId(wf.id)}${wf.error ? `：${wf.error}` : ''}`,
-      );
-      // 暂态错误裁决（仅当 end 的是当前活跃步）：
-      //   ok:true  → 重试/恢复成功 → 丢弃 pending llm_error，短暂显示"已恢复"后随刷新消失。
-      //   ok:false → 该步彻底失败 → 把暂态错误提升为永久红字（chat.error，进 scrollback 上方）。
-      if (setters.workflowCtx && setters.workflowCtx.activeStepId === wf.id) {
-        const pending = setters.workflowCtx.pendingLlmError;
-        if (wf.ok) {
-          if (pending) {
-            // 成功收回：留一条灰底"已恢复"提示，下一次状态行刷新自然覆盖消失
-            setters.setTransientError?.(`${figures.ok} ${wf.id} 已恢复（此前 LLM 调用失败已重试成功）`);
-          } else {
-            setters.setTransientError?.(null);
-          }
-        } else {
-          // 彻底失败：暂态升永久红字。优先用 step.error，回落到 pending llm_error。
-          const finalMsg = wf.error ?? pending;
-          if (finalMsg) setters.setError(finalMsg);
-          setters.setTransientError?.(null);
-        }
-        setters.workflowCtx.activeStepId = null;
-        setters.workflowCtx.pendingLlmError = null;
-      }
-      // 步骤完成：强制刷新 token（agent/llm 步骤可能写入大量上下文）
-      setters.bump();
-      return;
-    case 'workflow_step_skipped':
-      setters.emitProgressLine?.(`  ${figures.elbow} ${figures.skip} ${titleOrId(wf.id)}：${wf.reason ?? ''}`);
-      return;
-    case 'workflow_done':
-      setters.emitProgressLine?.(`${figures.ok} 工作流 ${wf.name} 完成`);
-      // 工作流结束：最终刷新（反映完整执行后的上下文量）
-      setters.bump();
-      return;
-  }
+  // ⚠️ 这里曾有一整块 `workflow_start` / `workflow_step_start` / `workflow_step_end` /
+  // `workflow_step_skipped` / `workflow_done` 的渲染逻辑（外加一个 activeStepId
+  // 状态机）。那是 yaml DSL 引擎的事件，随引擎一起删除后**一个发送方都不剩**，
+  // 只有测试自己合成它们 —— 纯死代码。
+  //
+  // V2 工作流发结构化 `workflow_progress`；旧插件仍可发 `plugin_progress`。
 
   // 收口到 LoopEvent：未识别的 PluginEvent type 走 default no-op
   const e = ev as LoopEvent;
@@ -1399,6 +1445,13 @@ export function handleEvent(
       setters.setRunningToolsMap(() => new Map());
       setters.bump();
       break;
+    case 'assistant_draft_discarded':
+      setters.flushStreamingBuffer();
+      setters.setStreamingText(() => '');
+      setters.cancelReasoningFlush();
+      setters.setReasoningPreview(() => '');
+      setters.setProgressStage('thinking');
+      break;
     case 'tool_start':
       // 把工具加入运行集合；并行多个工具时这里会累积。
       // v2: argsFriendly 是 loop.ts 通过 LoopEvent 扩展字段传过来的人话描述
@@ -1423,7 +1476,11 @@ export function handleEvent(
         const current = prev.get(e.toolCallId);
         if (!current) return prev;
         const next = new Map(prev);
-        next.set(e.toolCallId, { ...current, progress: e.message, progressDetail: e.detail });
+        next.set(e.toolCallId, {
+          ...current,
+          progress: e.message,
+          progressDetail: e.detail,
+        });
         return next;
       });
       setters.scheduleToolBump();
@@ -1482,33 +1539,12 @@ export function handleEvent(
         setters.bump();
         break;
       }
-      // 工作流步执行中的 max_turns 是可恢复截断信号：runner 会在共享 history 上续跑。
-      // 这里不要落入永久红字错误区；顶层非工作流 max_turns 仍保持原有错误展示。
-      if (
-        code === 'max_turns' &&
-        setters.workflowCtx &&
-        setters.workflowCtx.activeStepId !== null &&
-        setters.setTransientError
-      ) {
-        setters.setTransientError('↻ 当前步骤达到轮数预算，正在续跑…');
-        setters.bump();
-        break;
-      }
-      // 工作流步执行中的 llm_error：暂态而非永久红字 ——
-      // 该步通常会被重试，这里只暂存 + 喂 LiveArea 黄字，等 step_end 裁决去留。
-      // 非工作流场景（无活跃 step，或缺 setTransientError 降级）走原有永久红字路径。
-      if (
-        code === 'llm_error' &&
-        setters.workflowCtx &&
-        setters.workflowCtx.activeStepId !== null &&
-        setters.setTransientError
-      ) {
-        setters.workflowCtx.pendingLlmError = e.error;
-        setters.setTransientError(`⚠ LLM 调用失败（重试中）：${e.error}`);
-        setters.bump();
-        break;
-      }
-      // 其余：顶层 halt（无 code）、非工作流 llm_error、aborted 等 → 永久红字。
+      // 注：这里曾有两条「工作流步内的 max_turns / llm_error 降级成暂态黄字」分支，
+      // 都以 `workflowCtx.activeStepId !== null` 为前提。那个 id 由 yaml DSL 的
+      // workflow_step_start 事件写入，事件删除后恒为 null，两条分支永远走不到。
+      // 代码编排引擎把这两种错误在 `api.ts` 内部就地消化（`continue`，不外泄给顶层），
+      // 顶层根本收不到 —— 所以不是「少了个降级」，而是这层判断已无对象。
+      // 其余：顶层 halt（无 code）、llm_error、aborted 等 → 永久红字。
       setters.setError(e.error);
       setters.bump();
       break;
@@ -1535,6 +1571,14 @@ export function handleEvent(
         max: e.max,
         message: e.message,
       });
+      // 同时落一行进 scrollback。状态行是**覆盖刷新**的：一条二十步的工作流跑完，
+      // 状态行只剩最后一步，前面十九步去哪了、在哪一步失败的全查不到 —— 而排障
+      // 恰恰总发生在跑完之后。legacy 靠 workflow_step_* 事件做这件事，那套事件随
+      // yaml 引擎删了，这里由 plugin_progress 承担同一职责。
+      // 走 ephemeral 行：只进展示，不进 history、不被 saveContext 持久化。
+      if (typeof e.message === 'string' && e.message.length > 0) {
+        setters.emitProgressLine?.(e.message);
+      }
       // 重试进度也镜像到暂态行（覆盖刷新）：runner 在重试时发 "↻ 重试 x N/M…"。
       // 与 warning 分支互为补充（plugin_progress 文案更短，适合状态行下方一行）。
       if (
@@ -1546,6 +1590,24 @@ export function handleEvent(
       }
       setters.bump();
       break;
+    case 'workflow_progress': {
+      const indent = '  '.repeat(e.depth ?? 0);
+      const count =
+        e.current !== undefined && e.total !== undefined
+          ? `${e.current}/${e.total} `
+          : '';
+      const message = `${indent}${count}${e.message ?? e.phase}`;
+      setters.setPluginProgress({
+        pluginId: e.workflow,
+        current: e.current,
+        max: e.total,
+        message,
+      });
+      setters.emitProgressLine?.(message);
+      if (e.status === 'warning') setters.setTransientError?.(message);
+      setters.bump();
+      break;
+    }
     case 'reasoning':
       // reasoning delta 频率跟 text delta 一样高（60+/秒），不节流的话每个 delta 立即
       // setReasoningPreview → LiveArea rerender → Ink 重绘扛不住。