@zhin.js/agent 0.1.30 → 0.1.32

package/lib/zhin-agent/turn-pipeline.js

@@ -1,37 +1,33 @@
-import { getPlugin } from '@zhin.js/core';
-import { formatCompact, truncatePreview, Logger } from '@zhin.js/logger';
-import { createAgent } from '@zhin.js/ai';
+import { formatCompact, Logger } from '@zhin.js/logger';
+import { userMessagePlainText } from '@zhin.js/ai';
 import { resolveIMSessionIdFromToolContext } from '@zhin.js/ai';
 import { parseOutput } from '@zhin.js/ai';
 import { detectTone } from '@zhin.js/ai';
 import { ensureMcpConnectionsForBinding, getMcpToolsForBinding, } from '../orchestrator/mcp-lifecycle.js';
-import { applyExecPolicyToTools } from '../security/exec-policy.js';
-import { runWithBashToolContext } from '../security/bash-tool-context.js';
 import { triggerAIHook, createAIHookEvent } from '../hooks.js';
 import { resolveModelCandidates } from './model-resolver.js';
-import { streamChatWithHistory, streamChatWithVisionMedia } from './llm-runner.js';
-import { INBOUND_MEDIA_PARTS_EXTRA_KEY } from '../media/constants.js';
 import { mergeToolOutboundElements } from '../media/media-tool-bridge.js';
 import { providerSupportsVision } from '../media/vision-capability.js';
-import { buildSessionCreateInput, touchSession, buildHistoryMessages, formatUserContentForSession, resolveSessionIsNewBeforeCreate, } from './session-io.js';
+import { touchSession, resolveSessionIsNewBeforeCreate, beginTurnSession as beginTurnSessionIO, } from './session-io.js';
+import { buildTurnUserMessages } from './turn-user-message.js';
+import { runAgentLoopTextTurn, runAgentLoopVisionTurn } from './agent-loop-turn.js';
 import { buildEnhancedPersona } from './prompt.js';
-import { collectRuntimeTools, planToolRun } from './tool-runtime.js';
-import { sanitizeAssistantReply, stripThinkBlocks } from './text-sanitize.js';
-import { pruneHistoryWithBudget } from './context-budget.js';
+import { collectRuntimeTools } from './tool-runtime.js';
 import { buildMultimodalVisionSystemPrompt } from './prompt-assembly.js';
-import { formatToolCallsForUser } from './tool-calls-user-format.js';
-import { resolveModelHarness } from './model-harness.js';
-import { RESERVED_TOOL_NAMES, RESERVED_TOOL_NAME_PREFIXES } from '../reserved-tools.js';
-import { createOwnerOrchestratedToolResultTransform } from '../orchestrator/owner-confirm-orchestration.js';
-import { logPhase, usageLogFields } from './phase-trace.js';
 import { attachWebSearchLocale } from './web-search-locale-attach.js';
 import { EMPTY_USAGE } from './turn-metrics.js';
 import { resolveAgentToolsForTurn } from './tool-orchestration.js';
-import { buildAgentPathSystemPrompt, buildChatPathSystemPrompt, buildFastPathSystemPrompt, buildAgentUserMessage, } from './prompt-assembly.js';
+import { logPhase } from './phase-trace.js';
+import { buildVisionUserMessage, summarizeMultimodalParts } from './multimodal-message.js';
+import { DEFAULT_MULTIMODAL_CONFIG } from '../media/media-types.js';
 const logger = new Logger(null, 'ZhinAgent');
 const now = () => performance.now();
 function sessionDeps(host) {
-    return { chatHistory: host.chatHistory, imSessionStore: host.imSessionStore };
+    return {
+        imSessionStore: host.imSessionStore,
+        agentSessionStore: host.agentSessionStore,
+        contextRepository: host.contextRepository,
+    };
 }
 async function beginTurnSession(host, context) {
     const sessionKey = resolveIMSessionIdFromToolContext({
@@ -41,22 +37,27 @@ async function beginTurnSession(host, context) {
         sceneId: context.sceneId,
         senderId: context.senderId,
     });
-    const imSession = await host.imSessionStore.getOrCreateActive(buildSessionCreateInput(sessionKey, context));
-    return { sessionKey, sessionId: imSession.session_id };
+    return beginTurnSessionIO(sessionDeps(host), sessionKey, context);
 }
-export async function processTextTurn(host, content, context, externalTools = [], onChunk) {
+export async function processTextTurn(host, content, context, externalTools = [], onChunk, extras) {
     const t0 = now();
-    const { senderId, sceneId, platform, botId, messageId } = context;
-    const sessionUserContent = formatUserContentForSession(context, content);
+    const { senderId, platform, botId } = context;
+    const turnUser = buildTurnUserMessages(context, content);
     const userId = senderId || 'unknown';
     const sessionKey = resolveIMSessionIdFromToolContext({
         platform,
         botId,
         scope: context.scope,
-        sceneId,
+        sceneId: context.sceneId,
         senderId,
     });
-    const isNewSession = await resolveSessionIsNewBeforeCreate(sessionDeps(host), sessionKey, context);
+    const isNewSession = await resolveSessionIsNewBeforeCreate(sessionDeps(host), sessionKey);
+    if (extras?.deferredAutoContinue) {
+        logPhase(host.phaseConfig, 'turn.deferred_auto_continue', sessionKey, {});
+    }
+    else {
+        host.resetDeferredAutoContinueDepth(sessionKey);
+    }
     await host.waitForMemoryPersistence();
     const { sessionId } = await beginTurnSession(host, context);
     await host.emitter.dispatch('ai.processing.start', host.emitter.createPayload(sessionId, context, 'text', {
@@ -66,25 +67,24 @@ export async function processTextTurn(host, content, context, externalTools = []
         mode: 'text',
         provider: host.getTurnProvider().name,
     });
-    // 0. Rate limit
-    const rateCheck = host.rateLimiter.check(userId);
-    if (!rateCheck.allowed) {
-        logPhase(host.phaseConfig, 'turn.rate_limited', sessionId, { userId });
-        logger.debug(`[速率限制] 用户 ${userId} 被限制: ${rateCheck.message}`);
-        await host.emitter.dispatch('ai.processing.finish', host.emitter.createPayload(sessionId, context, 'text', {
-            path: 'rate_limited',
-            reply: rateCheck.message || '请稍后再试',
-            reason: 'rate_limited',
-        }));
-        await host.finalizeActiveTurn({ usage: EMPTY_USAGE, path: 'rate_limited' });
-        return parseOutput(rateCheck.message || '请稍后再试');
+    if (!extras?.deferredAutoContinue) {
+        const rateCheck = host.rateLimiter.check(userId);
+        if (!rateCheck.allowed) {
+            logPhase(host.phaseConfig, 'turn.rate_limited', sessionId, { userId });
+            logger.debug(`[速率限制] 用户 ${userId} 被限制: ${rateCheck.message}`);
+            await host.emitter.dispatch('ai.processing.finish', host.emitter.createPayload(sessionId, context, 'text', {
+                path: 'rate_limited',
+                reply: rateCheck.message || '请稍后再试',
+                reason: 'rate_limited',
+            }));
+            await host.finalizeActiveTurn({ usage: EMPTY_USAGE, path: 'rate_limited' });
+            return parseOutput(rateCheck.message || '请稍后再试');
+        }
     }
-    // 0.1 发射 typing 事件，由适配器插件自行决定如何响应
     host.emitter.emit('ai.typing.start', host.emitter.createPayload(sessionId, context, 'text', {
         reason: 'processing',
     }));
     host.beginActiveTurn();
-    // 0.5 工具上下文：web_search 语言（档案 preferred_language / language，否则默认中文）
     const contextForTools = await attachWebSearchLocale(context, userId, host.userProfiles);
     triggerAIHook(createAIHookEvent('message', 'received', sessionId, {
         userId,
@@ -93,7 +93,6 @@ export async function processTextTurn(host, content, context, externalTools = []
     })).catch(() => { });
     const turnBinding = host.activeBinding;
     const mcpServerNames = turnBinding?.mcpServers ?? [];
-    // 0.9 Lazy-connect MCP servers listed on active agent binding
     if (host.orchestrator && mcpServerNames.length > 0) {
         await ensureMcpConnectionsForBinding(host.orchestrator.mcps, mcpServerNames, (event) => {
             const payload = host.emitter.createPayload(sessionId, contextForTools, 'text', {
@@ -114,12 +113,11 @@ export async function processTextTurn(host, content, context, externalTools = []
             }
         });
     }
-    // 1. Collect tools
     const tFilter = now();
     const mcpTools = host.orchestrator && mcpServerNames.length > 0
         ? getMcpToolsForBinding(host.orchestrator.mcps, mcpServerNames)
         : [];
-    let allTools = collectRuntimeTools({
+    const allTools = collectRuntimeTools({
         content,
         context: contextForTools,
         externalTools,
@@ -128,7 +126,7 @@ export async function processTextTurn(host, content, context, externalTools = []
         externalRegistered: host.externalTools,
         sessionId,
         userId,
-        chatHistory: host.chatHistory,
+        imTranscriptStore: host.imTranscriptStore,
         userProfiles: host.userProfiles,
         mcpTools,
     });
@@ -141,323 +139,91 @@ export async function processTextTurn(host, content, context, externalTools = []
         tool_search: true,
         names: resolvedTools.map(t => t.name).join(',') || '(none)',
     }));
-    // 2. History + profile (parallel)
-    const tMem = now();
-    const [rawHistoryMessages, profileSummary] = await Promise.all([
-        buildHistoryMessages(sessionDeps(host), sessionId, context, sessionUserContent),
-        host.userProfiles.buildProfileSummary(userId),
-    ]);
-    const chatCandidates = resolveModelCandidates(host.getTurnProvider().models, host.modelRegistry, host.getTurnProvider().name, host.config, 'chat');
-    const { messages: historyMessages, result: pruneResult, budget: contextBudget, } = pruneHistoryWithBudget({
-        messages: rawHistoryMessages,
-        config: host.config,
-        provider: host.getTurnProvider(),
-        modelRegistry: host.modelRegistry,
-        model: chatCandidates[0],
-    });
-    if (pruneResult.droppedCount > 0) {
-        logger.debug(`[上下文窗口] 丢弃 ${pruneResult.droppedCount} 条历史消息 (${pruneResult.droppedTokens} tokens)`);
-    }
-    const memMs = (now() - tMem).toFixed(0);
-    logPhase(host.phaseConfig, 'context.ready', sessionId, { historyCount: historyMessages.length });
-    // 2.5 Tone + persona
+    const profileSummary = await host.userProfiles.buildProfileSummary(userId);
     const toneHint = host.config.toneAwareness ? detectTone(content).hint : '';
     const personaEnhanced = buildEnhancedPersona(host.config, profileSummary, toneHint);
-    // 3. No tools → chat path (prefer per-session model, then lightweight model)
-    if (allTools.length === 0) {
-        logPhase(host.phaseConfig, 'path.chat', sessionId, { toolCount: 0 });
-        const liteModel = host.config.chatLiteModel || undefined;
-        const chatSystemPrompt = buildChatPathSystemPrompt(host, personaEnhanced, contextForTools);
-        logger.debug(formatCompact({
-            mode: 'chat',
-            prompt_chars: chatSystemPrompt.length,
-            model: liteModel || chatCandidates[0] || undefined,
-        }));
-        const tLLM = now();
-        logPhase(host.phaseConfig, 'chat.llm.start', sessionId, { model: liteModel || chatCandidates[0] || '' });
-        const inboundVision = contextForTools.extra?.[INBOUND_MEDIA_PARTS_EXTRA_KEY];
-        const chatResult = inboundVision?.length
-            ? await streamChatWithVisionMedia({ provider: host.getTurnProvider(), modelRegistry: host.modelRegistry, config: host.config }, sessionUserContent, inboundVision, chatSystemPrompt, historyMessages, onChunk, liteModel || host.config.visionModel)
-            : await streamChatWithHistory({ provider: host.getTurnProvider(), modelRegistry: host.modelRegistry, config: host.config }, sessionUserContent, chatSystemPrompt, historyMessages, onChunk, liteModel);
-        let reply = sanitizeAssistantReply(chatResult.content);
-        await host.emitter.dispatch('ai.response', host.emitter.createPayload(sessionId, context, 'text', {
-            path: 'chat',
-            model: chatResult.model,
-            reply,
-        }));
-        const llmMs = (now() - tLLM).toFixed(0);
-        logPhase(host.phaseConfig, 'chat.llm.end', sessionId, {
-            durationMs: Number(llmMs),
-            ...usageLogFields(chatResult.usage ?? undefined),
-        });
-        logger.debug(formatCompact({
-            mode: 'chat',
-            filter_ms: filterMs,
-            mem_ms: memMs,
-            llm_ms: llmMs,
-            total_ms: Math.round(now() - t0),
-        }));
-        await touchSession(sessionDeps(host), sessionId);
-        if (isNewSession) {
-            host.emitSessionNewEvent(sessionId, context, 'text', sessionUserContent, reply);
-        }
-        await host.finalizeActiveTurn({
-            usage: chatResult.usage ?? EMPTY_USAGE,
-            path: 'chat',
-            model: chatResult.model,
-        });
-        await host.emitter.dispatch('ai.processing.finish', host.emitter.createPayload(sessionId, context, 'text', {
-            path: 'chat',
-            model: chatResult.model,
-            reply,
-        }));
-        host.emitter.emit('ai.typing.stop', host.emitter.createPayload(sessionId, context, 'text', {
-            reason: 'processing_complete',
-        }));
-        logPhase(host.phaseConfig, 'turn.end', sessionId, { path: 'chat' });
-        return parseOutput(reply);
-    }
-    logger.debug(`[工具路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, ${allTools.length} 工具 (${allTools.map(t => t.name).join(', ')})`);
-    // 4. Pre-executable tools
-    const preExecCandidates = allTools.filter(tool => tool.preExecutable);
-    const tPre = preExecCandidates.length > 0 ? now() : 0;
-    if (preExecCandidates.length > 0) {
-        logger.debug(`预执行: ${preExecCandidates.map(t => t.name).join(', ')}`);
-    }
-    const toolRun = await planToolRun(resolvedTools, host.config.preExecTimeout);
-    logPhase(host.phaseConfig, 'preexec.done', sessionId, {
-        mode: toolRun.mode,
-        preExecutedTools: toolRun.preExecution.tools.length,
-    });
-    const preData = toolRun.preExecution.data;
-    if (tPre > 0) {
-        logger.debug(`预执行耗时: ${(now() - tPre).toFixed(0)}ms`);
-    }
-    // 6. Path selection
-    let reply;
-    let agentToolCalls = [];
-    if (toolRun.mode === 'pre-exec-fast-path') {
-        logPhase(host.phaseConfig, 'path.pre_exec_fast', sessionId, { toolCount: allTools.length });
-        // Fast path
-        const tLLM = now();
-        const prompt = buildFastPathSystemPrompt(host, personaEnhanced, preData, contextForTools);
-        logger.debug(formatCompact({ mode: 'fast', prompt_chars: prompt.length }));
-        logPhase(host.phaseConfig, 'fast.llm.start', sessionId, { model: chatCandidates[0] || '' });
-        const fastResult = await streamChatWithHistory({ provider: host.getTurnProvider(), modelRegistry: host.modelRegistry, config: host.config }, sessionUserContent, prompt, historyMessages, onChunk);
-        reply = sanitizeAssistantReply(fastResult.content);
-        logPhase(host.phaseConfig, 'fast.llm.end', sessionId, {
-            durationMs: Math.round(now() - tLLM),
-            ...usageLogFields(fastResult.usage ?? undefined),
-        });
-        logger.debug(`[快速路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, LLM=${(now() - tLLM).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
-        await host.finalizeActiveTurn({
-            usage: fastResult.usage ?? EMPTY_USAGE,
-            path: 'fast',
-            model: fastResult.model,
-        });
-    }
-    else {
-        logPhase(host.phaseConfig, 'path.agent', sessionId, { toolCount: allTools.length });
-        const tAgent = now();
-        logger.debug(`Agent 路径: ${allTools.length} 个工具`);
-        const systemPrompt = await buildAgentPathSystemPrompt(host, {
-            content,
-            context: contextForTools,
+    const chatCandidates = resolveModelCandidates(host.getTurnProvider().models, host.modelRegistry, host.getTurnProvider().name, host.config, 'chat');
+    logPhase(host.phaseConfig, 'path.agent_loop', sessionId, { toolCount: allTools.length });
+    const userMessages = extras?.prebuiltMessages?.length
+        ? extras.prebuiltMessages
+        : turnUser.promptMessages;
+    const loopResult = await host.promptController.schedule({
+        sessionKey,
+        sessionId,
+        userMessages,
+        context,
+        onChunk,
+        execute: (initialMessages, hooks, signal, _turnId) => runAgentLoopTextTurn({
+            host,
             sessionId,
+            userMessageExtra: turnUser.userMessageExtra,
+            rawContent: turnUser.rawContent,
+            context,
+            contextForTools,
+            allTools,
+            resolvedTools,
             personaEnhanced,
-            preData,
+            modelId: chatCandidates[0] || host.getTurnProvider().models[0] || 'gpt-4o-mini',
+            modelCandidates: chatCandidates,
+            onChunk,
+            initialMessages,
+            promptHooks: hooks,
+            signal,
             deferredStats,
-        });
-        logger.debug(formatCompact({ mode: 'agent', prompt_chars: systemPrompt.length }));
-        logger.debug(`[System Prompt Full]\n${systemPrompt}\n---END---`);
-        const agentTools = applyExecPolicyToTools(host.config, resolvedTools, {
-            approvalMode: host.config.execApprovalMode,
-        });
-        // Adaptive maxIterations: boost when skills are active (multi-step skill flows)
-        const SKILL_ITERATION_BOOST = 3;
-        const hasSkillActivation = agentTools.some(t => t.name === 'activate_skill' || t.name === 'install_skill');
-        const harness = resolveModelHarness(host.getTurnProvider().name, chatCandidates[0] || '', host.config.modelHarness);
-        const baseIterations = harness.maxIterations ?? host.config.maxIterations;
-        const effectiveMaxIterations = hasSkillActivation
-            ? baseIterations + SKILL_ITERATION_BOOST
-            : baseIterations;
-        logPhase(host.phaseConfig, 'harness.resolved', sessionId, {
-            model: chatCandidates[0] || '',
-            harnessMaxIterations: harness.maxIterations ?? null,
-            effectiveMaxIterations,
-        });
-        let orchestrationPlugin = host.emitter.getHostPlugin() ?? undefined;
-        if (!orchestrationPlugin) {
-            try {
-                orchestrationPlugin = getPlugin().root ?? getPlugin();
-            }
-            catch {
-                logger.warn(formatCompact({ warn: 'no_host_plugin' }));
-            }
-        }
-        const llmAgent = createAgent(host.getTurnProvider(), {
-            model: chatCandidates[0],
-            modelFallbacks: chatCandidates.slice(1),
-            systemPrompt,
-            tools: agentTools,
-            maxIterations: effectiveMaxIterations,
-            turnTimeout: host.config.timeout,
-            contextWindow: contextBudget.contextWindow,
-            reservedToolNames: RESERVED_TOOL_NAMES,
-            reservedToolNamePrefixes: RESERVED_TOOL_NAME_PREFIXES,
-            transformToolResult: createOwnerOrchestratedToolResultTransform({
-                toolContext: contextForTools,
-                disableHardOrchestration: false,
-                plugin: orchestrationPlugin,
-            }),
-            policyDenialStopAfter: host.config.policyDenialStopAfter,
-        });
-        llmAgent.on('thinking', (message) => {
-            host.emitter.emit('ai.thinking', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                thinking: message,
-            }));
-        });
-        llmAgent.on('tool_call', (toolName, args) => {
-            host.emitter.emit('ai.tool.call', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                toolName,
-                args,
-            }));
-        });
-        llmAgent.on('tool_result', (toolName, result) => {
-            host.emitter.emit('ai.tool.result', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                toolName,
-                result,
-            }));
-        });
-        llmAgent.on('compaction', (info) => {
-            host.emitSessionCompactEvent(sessionId, contextForTools, 'text', info);
-        });
-        const userMessageWithHistory = buildAgentUserMessage(historyMessages, sessionUserContent);
-        let result;
-        try {
-            await host.emitter.dispatch('ai.agent.start', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                model: chatCandidates[0] || undefined,
-            }));
-            logPhase(host.phaseConfig, 'agent.run.start', sessionId, { model: chatCandidates[0] || '' });
-            result = await runWithBashToolContext(contextForTools, () => llmAgent.run(userMessageWithHistory, []));
-            logPhase(host.phaseConfig, 'agent.run.end', sessionId, {
-                iterations: result.iterations,
-                durationMs: Math.round(now() - tAgent),
-                ...usageLogFields(result.usage),
-            });
-            await host.emitter.dispatch('ai.agent.finish', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                model: result.model ?? (chatCandidates[0] || undefined),
-                iterations: result.iterations,
-            }));
-        }
-        catch (error) {
-            await host.emitter.dispatch('ai.processing.error', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-                path: 'agent',
-                error: error instanceof Error ? error.message : String(error),
-            }));
-            throw error;
-        }
-        finally {
-            llmAgent.dispose();
-        }
-        agentToolCalls = result.toolCalls;
-        const spawnedSubagent = result.toolCalls.some(tc => tc.tool === 'spawn_task');
-        if (spawnedSubagent) {
-            await host.turnTracker.waitForPendingSubagents();
-        }
-        const delegatedOnly = spawnedSubagent
-            && !result.toolCalls.some(tc => tc.tool === 'run_deferred_task')
-            && !result.toolCalls.some(tc => tc.tool === 'generate_image'
-                && tc.result
-                && typeof tc.result === 'object'
-                && typeof tc.result.image === 'string');
-        if (delegatedOnly) {
-            reply = '';
-        }
-        else {
-            reply = sanitizeAssistantReply(result.content, {
-                toolSummary: formatToolCallsForUser(result.toolCalls),
-            });
-        }
-        await host.emitter.dispatch('ai.response', host.emitter.createPayload(sessionId, contextForTools, 'text', {
-            path: 'agent',
-            model: result.model ?? (chatCandidates[0] || undefined),
-            iterations: result.iterations,
-            reply,
-        }));
-        logger.debug(formatCompact({
-            agent_answer: truncatePreview(reply, 480),
-            tool_calls: result.toolCalls.length,
-            ...(result.toolCalls.length
-                ? { tools: result.toolCalls.map(tc => tc.tool).join(',') }
-                : {}),
-        }));
-        for (const tc of result.toolCalls) {
-            const preview = toolCallResultDebugPreview(tc);
-            logger.debug(formatCompact({
-                tool_result: tc.tool,
-                preview: truncatePreview(preview, 480),
-            }));
-        }
-        logger.debug(`[Agent 路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, Agent=${(now() - tAgent).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
-        await host.finalizeActiveTurn({
-            usage: result.usage,
-            path: 'agent',
-            iterations: result.iterations,
-            model: result.model ?? (chatCandidates[0] || undefined),
-        });
-    }
+        }),
+    });
+    const reply = loopResult.reply;
+    await host.emitter.dispatch('ai.response', host.emitter.createPayload(sessionId, context, 'text', {
+        path: loopResult.path,
+        model: loopResult.model,
+        iterations: loopResult.iterations,
+        reply,
+    }));
     await touchSession(sessionDeps(host), sessionId);
     if (isNewSession) {
-        host.emitSessionNewEvent(sessionId, context, 'text', sessionUserContent, reply);
+        host.emitSessionNewEvent(sessionId, context, 'text', turnUser.rawContent, reply);
     }
+    await host.finalizeActiveTurn({
+        usage: loopResult.usage,
+        path: loopResult.path,
+        iterations: loopResult.iterations,
+        model: loopResult.model,
+    });
     triggerAIHook(createAIHookEvent('message', 'sent', sessionId, {
         userId,
         content: reply,
         platform: platform || '',
     })).catch(() => { });
     await host.emitter.dispatch('ai.processing.finish', host.emitter.createPayload(sessionId, context, 'text', {
-        path: toolRun.mode === 'pre-exec-fast-path' ? 'fast' : 'agent',
+        path: loopResult.path,
+        model: loopResult.model,
         reply,
     }));
-    logPhase(host.phaseConfig, 'turn.end', sessionId, { path: toolRun.mode === 'pre-exec-fast-path' ? 'fast' : 'agent' });
     host.emitter.emit('ai.typing.stop', host.emitter.createPayload(sessionId, context, 'text', {
         reason: 'processing_complete',
     }));
-    const outbound = mergeToolOutboundElements(parseOutput(reply), agentToolCalls);
+    logPhase(host.phaseConfig, 'turn.end', sessionId, {
+        path: loopResult.path,
+        filter_ms: filterMs,
+        total_ms: Math.round(now() - t0),
+    });
+    const outbound = mergeToolOutboundElements(parseOutput(reply), loopResult.toolCalls);
     if (!reply.trim() && outbound.length === 0)
         return [];
     return outbound;
 }
-function toolCallResultDebugPreview(tc) {
-    if (tc.tool === 'generate_image' && tc.result && typeof tc.result === 'object' && !Array.isArray(tc.result)) {
-        const image = tc.result.image;
-        const len = typeof image === 'string' ? image.length : 0;
-        return len > 0 ? `[image generated, ${len} b64 chars]` : '[generate_image: no image field]';
-    }
-    if (tc.tool === 'voice_tts' && tc.result && typeof tc.result === 'object' && !Array.isArray(tc.result)) {
-        const audio = tc.result.audio;
-        const len = typeof audio === 'string' ? audio.length : 0;
-        return len > 0 ? `[audio generated, ${len} b64 chars]` : '[voice_tts: no audio field]';
-    }
-    return typeof tc.result === 'string' ? tc.result : JSON.stringify(tc.result);
-}
+/** @deprecated 仅保留类型引用；多模态 turn 已统一 agentLoop */
 export async function processMultimodalTurn(host, parts, context, onChunk) {
-    const { senderId, sceneId, platform, botId } = context;
+    const { senderId, platform, botId } = context;
     const userId = senderId || 'unknown';
     const sessionKey = resolveIMSessionIdFromToolContext({
         platform,
         botId,
         scope: context.scope,
-        sceneId,
+        sceneId: context.sceneId,
         senderId,
     });
-    const isNewSession = await resolveSessionIsNewBeforeCreate(sessionDeps(host), sessionKey, context);
+    const isNewSession = await resolveSessionIsNewBeforeCreate(sessionDeps(host), sessionKey);
     await host.waitForMemoryPersistence();
     const { sessionId } = await beginTurnSession(host, context);
     await host.emitter.dispatch('ai.processing.start', host.emitter.createPayload(sessionId, context, 'multimodal'));
@@ -475,54 +241,11 @@ export async function processMultimodalTurn(host, parts, context, onChunk) {
         reason: 'processing',
     }));
     host.beginActiveTurn();
-    const textFragmentsEarly = [];
-    for (const p of parts) {
-        if (p.type === 'text')
-            textFragmentsEarly.push(p.text);
-    }
-    const textContentEarly = textFragmentsEarly.join(' ') || '[多模态消息]';
-    const sessionUserContentEarly = formatUserContentForSession(context, textContentEarly);
-    const rawHistoryMessages = await buildHistoryMessages(sessionDeps(host), sessionId, context, sessionUserContentEarly);
+    const supportsVision = providerSupportsVision(host.getTurnProvider());
+    const textContent = summarizeMultimodalParts(parts, supportsVision);
+    const turnUser = buildTurnUserMessages(context, textContent);
     const profileSummary = await host.userProfiles.buildProfileSummary(userId);
     const personaEnhanced = host.buildDisciplinedPrompt(buildEnhancedPersona(host.config, profileSummary, ''));
-    const textFragments = [];
-    const llmParts = [];
-    const supportsVision = providerSupportsVision(host.getTurnProvider());
-    for (const p of parts) {
-        switch (p.type) {
-            case 'text':
-                textFragments.push(p.text);
-                llmParts.push(p);
-                break;
-            case 'image_url':
-                textFragments.push('[图片]');
-                if (supportsVision)
-                    llmParts.push(p);
-                else
-                    llmParts.push({ type: 'text', text: '[用户发送了一张图片]' });
-                break;
-            case 'video_url':
-                textFragments.push('[视频]');
-                llmParts.push({ type: 'text', text: `[用户发送了一个视频: ${p.video_url.url}]` });
-                break;
-            case 'audio':
-                textFragments.push('[音频]');
-                if (supportsVision)
-                    llmParts.push(p);
-                else
-                    llmParts.push({ type: 'text', text: '[用户发送了一段音频]' });
-                break;
-            case 'face':
-                textFragments.push(p.face.text || `[表情:${p.face.id}]`);
-                llmParts.push({
-                    type: 'text',
-                    text: p.face.text ? `[表情: ${p.face.text}]` : `[表情ID: ${p.face.id}]`,
-                });
-                break;
-        }
-    }
-    const textContent = textFragments.join(' ') || '[多模态消息]';
-    const sessionUserContent = formatUserContentForSession(context, textContent);
     const visionSystemPrompt = await buildMultimodalVisionSystemPrompt(host, {
         context,
         sessionId,
@@ -530,95 +253,58 @@ export async function processMultimodalTurn(host, parts, context, onChunk) {
         personaEnhanced,
     });
     const visionCandidates = resolveModelCandidates(host.getTurnProvider().models, host.modelRegistry, host.getTurnProvider().name, host.config, 'vision');
-    const { messages: historyMessages, result: pruneResult } = pruneHistoryWithBudget({
-        messages: rawHistoryMessages,
-        config: host.config,
-        provider: host.getTurnProvider(),
-        modelRegistry: host.modelRegistry,
-        model: visionCandidates[0],
-    });
-    if (pruneResult.droppedCount > 0) {
-        logger.debug(`[多模态上下文窗口] 丢弃 ${pruneResult.droppedCount} 条历史消息 (${pruneResult.droppedTokens} tokens)`);
+    logPhase(host.phaseConfig, 'path.agent_loop', sessionId, { mode: 'multimodal' });
+    const userMessage = await buildVisionUserMessage(userMessagePlainText(turnUser.promptMessages[0]), parts, supportsVision, DEFAULT_MULTIMODAL_CONFIG.maxFileBytes);
+    let loopResult;
+    try {
+        loopResult = await host.promptController.schedule({
+            sessionKey,
+            sessionId,
+            userMessages: [userMessage],
+            context,
+            onChunk,
+            execute: (initialMessages, hooks, signal, _turnId) => runAgentLoopVisionTurn({
+                host,
+                sessionId,
+                context,
+                visionSystemPrompt,
+                userMessages: initialMessages,
+                modelCandidates: visionCandidates,
+                onChunk,
+                promptHooks: hooks,
+                signal,
+            }),
+        });
     }
-    const messages = [
-        { role: 'system', content: visionSystemPrompt },
-        ...historyMessages,
-        { role: 'user', content: llmParts },
-    ];
-    let reply = '';
-    let lastUsage = null;
-    let usedVisionModel = visionCandidates[0] || '';
-    for (let i = 0; i < visionCandidates.length; i++) {
-        const visionModel = visionCandidates[i];
-        usedVisionModel = visionModel;
-        try {
-            reply = '';
-            for await (const chunk of host.getTurnProvider().chatStream({ model: visionModel, messages })) {
-                if (chunk.usage)
-                    lastUsage = chunk.usage;
-                const delta = chunk.choices?.[0]?.delta;
-                if (!delta)
-                    continue;
-                const text = typeof delta.content === 'string' ? delta.content : '';
-                if (text) {
-                    reply += text;
-                    if (onChunk)
-                        onChunk(text, reply);
-                }
-            }
-            reply = stripThinkBlocks(reply);
-            if (!reply) {
-                logger.warn(formatCompact({ mode: 'multimodal', fallback: visionModel, reason: 'empty_stream' }));
-                const response = await host.getTurnProvider().chat({ model: visionModel, messages });
-                if (response.usage)
-                    lastUsage = response.usage;
-                const msg = response.choices[0]?.message?.content;
-                reply = stripThinkBlocks(typeof msg === 'string' ? msg : '');
-            }
-            if (reply)
-                break;
-        }
-        catch (err) {
-            const isLast = i === visionCandidates.length - 1;
-            if (isLast) {
-                try {
-                    const response = await host.getTurnProvider().chat({ model: visionModel, messages });
-                    if (response.usage)
-                        lastUsage = response.usage;
-                    const msg = response.choices[0]?.message?.content;
-                    reply = stripThinkBlocks(typeof msg === 'string' ? msg : '');
-                }
-                catch { /* all candidates exhausted */ }
-            }
-            else {
-                logger.warn(formatCompact({
-                    mode: 'multimodal',
-                    fallback: `${visionModel}→${visionCandidates[i + 1]}`,
-                    error: truncatePreview(err.message),
-                }));
-            }
-        }
+    catch {
+        loopResult = {
+            reply: '抱歉，我无法理解这条消息。',
+            usage: EMPTY_USAGE,
+            path: 'multimodal',
+            iterations: 0,
+            model: visionCandidates[0] || '',
+            toolCalls: [],
+        };
     }
-    if (!reply)
-        reply = '抱歉，我无法理解这条消息。';
-    reply = sanitizeAssistantReply(reply);
+    const reply = loopResult.reply;
     await host.emitter.dispatch('ai.response', host.emitter.createPayload(sessionId, context, 'multimodal', {
         path: 'multimodal',
-        model: usedVisionModel,
+        model: loopResult.model,
         reply,
     }));
     await touchSession(sessionDeps(host), sessionId);
     if (isNewSession) {
-        host.emitSessionNewEvent(sessionId, context, 'multimodal', sessionUserContent, reply);
+        host.emitSessionNewEvent(sessionId, context, 'multimodal', turnUser.rawContent, reply);
     }
     await host.finalizeActiveTurn({
-        usage: lastUsage ?? EMPTY_USAGE,
+        usage: loopResult.usage,
         path: 'multimodal',
-        model: usedVisionModel,
+        model: loopResult.model,
+        iterations: loopResult.iterations,
     });
     await host.emitter.dispatch('ai.processing.finish', host.emitter.createPayload(sessionId, context, 'multimodal', {
         path: 'multimodal',
-        model: usedVisionModel,
+        model: loopResult.model,
         reply,
     }));
     host.emitter.emit('ai.typing.stop', host.emitter.createPayload(sessionId, context, 'multimodal', {