@ynhcj/xiaoyi-channel 1.1.24 → 1.1.26

package/dist/src/bot.js

@@ -1,5 +1,4 @@
 import { getXYRuntime } from "./runtime.js";
-import { setCachedContext } from "./steer-injector.js";
 import { createXYReplyDispatcher } from "./reply-dispatcher.js";
 import { parseA2AMessage, extractTextFromParts, extractFileParts, extractPushId, extractDeviceType, extractTriggerData } from "./parser.js";
 import { downloadFilesFromParts } from "./file-download.js";
@@ -13,7 +12,9 @@ import { getPushDataById } from "./utils/pushdata-manager.js";
 import { selfEvolutionManager } from "./utils/self-evolution-manager.js";
 import { saveRuntimeInfo } from "./utils/runtime-manager.js";
 import { toolCallNudgeManager } from "./utils/tool-call-nudge-manager.js";
-import { registerTaskId, decrementTaskIdRef, lockTaskId, unlockTaskId, hasActiveTask, } from "./task-manager.js";
+import { setCsplSteerContext } from "./cspl/steer-context.js";
+import { registerTaskId, decrementTaskIdRef, hasActiveTask, } from "./task-manager.js";
+import { logger } from "./utils/logger.js";
 /**
  * Handle an incoming A2A message.
  * This is the main entry point for message processing.
@@ -21,10 +22,8 @@ import { registerTaskId, decrementTaskIdRef, lockTaskId, unlockTaskId, hasActive
  */
 export async function handleXYMessage(params) {
     const { cfg, runtime, message, accountId, webSocketSessionId } = params;
-    const log = runtime?.log ?? console.log;
-    const error = runtime?.error ?? console.error;
-    // 每次收到消息时更新缓存，供 steer 注入使用
-    setCachedContext(cfg, runtime, accountId);
+    // Cache context for CSPL steer injection (after_tool_call hook)
+    setCsplSteerContext(cfg, runtime);
     // Get runtime (already validated in monitor.ts, but get reference for use)
     const core = getXYRuntime();
     try {
@@ -36,7 +35,7 @@ export async function handleXYMessage(params) {
             if (!sessionId) {
                 throw new Error("clearContext request missing sessionId in params");
             }
-            log(`Clear context request for session ${sessionId}`);
+            logger.log(`Clear context request for session ${sessionId}`);
             const config = resolveXYConfig(cfg);
             await sendClearContextResponse({
                 config,
@@ -52,7 +51,7 @@ export async function handleXYMessage(params) {
             if (!sessionId) {
                 throw new Error("tasks/cancel request missing sessionId in params");
             }
-            log(`Tasks cancel request for session ${sessionId}, task ${taskId}`);
+            logger.log(`Tasks cancel request for session ${sessionId}, task ${taskId}`);
             const config = resolveXYConfig(cfg);
             await sendTasksCancelResponse({
                 config,
@@ -68,18 +67,18 @@ export async function handleXYMessage(params) {
         // 如果消息中包含 Trigger 事件数据，直接返回 pushData 内容，不走正常流程
         const triggerData = extractTriggerData(parsed.parts);
         if (triggerData) {
-            log(`[BOT] 📌 Detected Trigger message with pushDataId: ${triggerData.pushDataId}`);
-            log(`[BOT]   - Session ID: ${parsed.sessionId}`);
-            log(`[BOT]   - Task ID: ${parsed.taskId}`);
+            logger.log(`[BOT] 📌 Detected Trigger message with pushDataId: ${triggerData.pushDataId}`);
+            logger.log(`[BOT]   - Session ID: ${parsed.sessionId}`);
+            logger.log(`[BOT]   - Task ID: ${parsed.taskId}`);
             try {
                 // 读取 pushData
                 const pushDataItem = await getPushDataById(triggerData.pushDataId);
                 if (!pushDataItem) {
-                    error(`[BOT] ❌ pushData not found for ID: ${triggerData.pushDataId}`);
+                    logger.error(`[BOT] ❌ pushData not found for ID: ${triggerData.pushDataId}`);
                     return;
                 }
-                log(`[BOT] ✅ Found pushData, sending direct response`);
-                log(`[BOT]   - pushDataId: ${pushDataItem.pushDataId}`);
+                logger.log(`[BOT] ✅ Found pushData, sending direct response`);
+                logger.log(`[BOT]   - pushDataId: ${pushDataItem.pushDataId}`);
                 const config = resolveXYConfig(cfg);
                 // 直接发送响应（final=true，不走 openclaw 流程）
                 await sendA2AResponse({
@@ -91,56 +90,52 @@ export async function handleXYMessage(params) {
                     append: false,
                     final: true,
                 });
-                log(`[BOT] ✅ Trigger response sent successfully, exiting early`);
+                logger.log(`[BOT] ✅ Trigger response sent successfully, exiting early`);
                 return; // 提前返回，不继续处理
             }
             catch (err) {
-                error(`[BOT] ❌ Failed to handle Trigger message:`, err);
+                logger.error(`[BOT] ❌ Failed to handle Trigger message:`, err);
                 return;
             }
         }
         // ========================================
-        // 🔑 检测steer模式和是否是第二条消息
-        const isSteerMode = cfg.messages?.queue?.mode === "steer";
-        const isSecondMessage = isSteerMode && hasActiveTask(parsed.sessionId);
-        if (isSecondMessage) {
-            log(`[BOT] 🔄 STEER MODE - Second message detected (will be follower)`);
-            log(`[BOT]   - Session: ${parsed.sessionId}`);
-            log(`[BOT]   - New taskId: ${parsed.taskId} (will replace current)`);
+        // 🔑 注册taskId（检测是否是已有活跃任务的 session）
+        const isUpdate = hasActiveTask(parsed.sessionId);
+        const skipReg = params.skipRegistration === true;
+        if (isUpdate) {
+            logger.log(`[BOT] 🔄 STEER MODE - Second message detected (core will handle steer)`);
+            logger.log(`[BOT]   - Session: ${parsed.sessionId}`);
+            logger.log(`[BOT]   - New taskId: ${parsed.taskId}`);
         }
-        // 🔑 注册taskId（第二条消息会覆盖第一条的taskId）
-        const { isUpdate, refCount } = registerTaskId(parsed.sessionId, parsed.taskId, parsed.messageId, { incrementRef: true } // 增加引用计数
-        );
-        // 🔑 如果是第一条消息，锁定taskId防止被过早清理
-        if (!isUpdate) {
-            lockTaskId(parsed.sessionId);
-            log(`[BOT] 🔒 Locked taskId for first message`);
-        }
-        // Extract and update push_id if present
-        const pushId = extractPushId(parsed.parts);
-        if (pushId) {
-            log(`[BOT] 📌 Extracted push_id from user message`);
-            configManager.updatePushId(parsed.sessionId, pushId);
-            // 持久化 pushId 到本地文件（异步，不阻塞主流程）
-            addPushId(pushId).catch((err) => {
-                error(`[BOT] Failed to persist pushId:`, err);
+        // Steer injections skip taskId registration to avoid overwriting the active taskId
+        if (!skipReg) {
+            registerTaskId(parsed.sessionId, parsed.taskId, parsed.messageId);
+            // Extract and update push_id if present
+            const pushId = extractPushId(parsed.parts);
+            if (pushId) {
+                logger.log(`[BOT] 📌 Extracted push_id from user message`);
+                configManager.updatePushId(parsed.sessionId, pushId);
+                // 持久化 pushId 到本地文件（异步，不阻塞主流程）
+                addPushId(pushId).catch((err) => {
+                    logger.error(`[BOT] Failed to persist pushId:`, err);
+                });
+            }
+            else {
+                logger.log(`[BOT] ℹ️  No push_id found in message, will use config default`);
+            }
+            // 保存 runtime 信息到 .xiaoyiruntime 文件（异步，不阻塞主流程）
+            saveRuntimeInfo(webSocketSessionId || parsed.sessionId, // SESSION_ID (WebSocket 层级，如果没有则 fallback)
+            parsed.sessionId, // CONVERSATION_ID (param 里的 sessionId)
+            parsed.taskId // TASK_ID (param.id)
+            ).catch((err) => {
+                logger.error(`[BOT] Failed to save runtime info:`, err);
             });
         }
-        else {
-            log(`[BOT] ℹ️  No push_id found in message, will use config default`);
-        }
-        // Extract deviceType if present (same level as push_id in systemVariables)
+        // Extract deviceType if present (always parse — used in ctxPayload.MessageSid)
         const deviceType = extractDeviceType(parsed.parts);
         if (deviceType) {
-            log(`[BOT] 📱 Extracted deviceType from user message: ${deviceType}`);
+            logger.log(`[BOT] 📱 Extracted deviceType from user message: ${deviceType}`);
         }
-        // 保存 runtime 信息到 .xiaoyiruntime 文件（异步，不阻塞主流程）
-        saveRuntimeInfo(webSocketSessionId || parsed.sessionId, // SESSION_ID (WebSocket 层级，如果没有则 fallback)
-        parsed.sessionId, // CONVERSATION_ID (param 里的 sessionId)
-        parsed.taskId // TASK_ID (param.id)
-        ).catch((err) => {
-            error(`[BOT] Failed to save runtime info:`, err);
-        });
         // Resolve configuration (needed for status updates)
         const config = resolveXYConfig(cfg);
         // ✅ Resolve agent route (following feishu pattern)
@@ -155,53 +150,95 @@ export async function handleXYMessage(params) {
                 id: parsed.sessionId, // ✅ Use sessionId to share context within the same conversation session
             },
         });
-        log(`xy: resolved route accountId=${route.accountId}, sessionKey=${route.sessionKey}`);
-        registerSession(route.sessionKey, {
-            config,
-            sessionId: parsed.sessionId,
-            taskId: parsed.taskId,
-            messageId: parsed.messageId,
-            agentId: route.accountId,
-        });
-        // 🔑 发送初始状态更新（第二条消息也要发，用新taskId）
-        log(`[STATUS] Sending initial status update for session ${parsed.sessionId}`);
-        void sendStatusUpdate({
-            config,
-            sessionId: parsed.sessionId,
-            taskId: parsed.taskId,
-            messageId: parsed.messageId,
-            text: isSecondMessage ? "新消息已接收，正在处理..." : "任务正在处理中，请稍候~",
-            state: "working",
-        }).catch((err) => {
-            error(`Failed to send initial status update:`, err);
-        });
+        logger.log(`xy: resolved route accountId=${route.accountId}, sessionKey=${route.sessionKey}`);
+        // Steer injections skip session registration to avoid refCount leaks
+        if (!skipReg) {
+            registerSession(route.sessionKey, {
+                config,
+                sessionId: parsed.sessionId,
+                taskId: parsed.taskId,
+                messageId: parsed.messageId,
+                agentId: route.accountId,
+                deviceType,
+            });
+            // 🔑 发送初始状态更新
+            logger.log(`[STATUS] Sending initial status update for session ${parsed.sessionId}`);
+            void sendStatusUpdate({
+                config,
+                sessionId: parsed.sessionId,
+                taskId: parsed.taskId,
+                messageId: parsed.messageId,
+                text: "任务正在处理中，请稍候~",
+                state: "working",
+            }).catch((err) => {
+                logger.error(`Failed to send initial status update:`, err);
+            });
+        }
         // Extract text and files from parts
         const text = extractTextFromParts(parsed.parts);
         let textForAgent = text || "";
-        if (route.sessionKey && textForAgent) {
+        // Self-evolution keyword nudge — only for real user messages, not steer injections
+        if (!skipReg && route.sessionKey && textForAgent) {
             try {
                 const selfEvolutionEnabled = await selfEvolutionManager.isEnabled();
                 if (selfEvolutionEnabled && shouldNudgeForSelfEvolutionKeyword(textForAgent)) {
                     const shouldNudge = toolCallNudgeManager.tryMarkKeywordNudge(route.sessionKey);
-                    log(`[SELF_EVOLUTION] Keyword check hit during inbound build: sessionKey=${route.sessionKey}, shouldNudge=${shouldNudge}`);
+                    logger.log(`[SELF_EVOLUTION] Keyword check hit during inbound build: sessionKey=${route.sessionKey}, shouldNudge=${shouldNudge}`);
                     if (shouldNudge) {
                         const augmented = appendSelfEvolutionKeywordNudge(textForAgent);
                         textForAgent = augmented.text;
                         if (augmented.appended) {
-                            log(`[SELF_EVOLUTION] Keyword-triggered inline nudge appended: sessionKey=${route.sessionKey}`);
+                            logger.log(`[SELF_EVOLUTION] Keyword-triggered inline nudge appended: sessionKey=${route.sessionKey}`);
                         }
                     }
                 }
             }
             catch (selfEvolutionError) {
-                error(`[SELF_EVOLUTION] Failed to append inline keyword nudge: ${String(selfEvolutionError)}`);
+                logger.error(`[SELF_EVOLUTION] Failed to append inline keyword nudge: ${String(selfEvolutionError)}`);
             }
         }
-        const fileParts = extractFileParts(parsed.parts);
-        // Download files to local disk
-        const downloadedFiles = await downloadFilesFromParts(fileParts);
-        console.log("Downloaded files:", JSON.stringify(downloadedFiles, null, 2));
-        const mediaPayload = buildXYMediaPayload(downloadedFiles);
+        // 🔑 Steer消息: 跳过旧路径直接进入 streaming-signal 队列
+        // /steer 前缀由 dispatchSteerWhenReady 内部添加
+        if (isUpdate) {
+            // 立即释放 init gate——steer 不走 withReplyDispatcher 的 run()
+            // 回调，onInitComplete 永远不会被触发。如果不释放，后续消息
+            // 会被 globalDispatchInitGate 永久阻塞。
+            params.onInitComplete?.();
+            // Steer 也支持文件 —— 提取并下载，附带到 mediaPayload
+            const steerFileParts = extractFileParts(parsed.parts);
+            const steerDownloadedFiles = await downloadFilesFromParts(steerFileParts);
+            const steerMediaPayload = buildXYMediaPayload(steerDownloadedFiles);
+            if (steerFileParts.length > 0) {
+                logger.log(`[BOT] 📎 Steer message with files: ${steerFileParts.length} file(s)`);
+            }
+            logger.log(`[BOT] 🔄 Steer message — enqueuing to streaming-signal queue`);
+            await enqueueSteer({
+                sessionId: parsed.sessionId,
+                sessionKey: route.sessionKey,
+                steerText: textForAgent, // 原始文本，不带 /steer 前缀
+                mediaPayload: steerMediaPayload,
+                cfg,
+                runtime,
+                parsed,
+                route,
+                deviceType,
+            });
+            logger.log(`[BOT] ✅ Steer queue completed for session: ${parsed.sessionId}`);
+            logger.log(`xy: dispatch complete (session=${parsed.sessionId})`);
+            return;
+        }
+        // ── First message (non-steer) path below ──────────────────────
+        // 🔑 立即创建 streaming 信号——必须在文件下载等耗时操作之前，
+        // 否则 steer 消息的 dispatchSteerWhenReady 会找不到信号而跳过等待。
+        createStreamingSignal(parsed.sessionId);
+        // File download — only for real user messages, steer injections have no files
+        let mediaPayload = {};
+        if (!skipReg) {
+            const fileParts = extractFileParts(parsed.parts);
+            const downloadedFiles = await downloadFilesFromParts(fileParts);
+            logger.log("Downloaded files:", JSON.stringify(downloadedFiles, null, 2));
+            mediaPayload = buildXYMediaPayload(downloadedFiles);
+        }
         // Resolve envelope format options (following feishu pattern)
         const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
         // Build message body with speaker prefix (following feishu pattern)
@@ -233,7 +270,7 @@ export async function handleXYMessage(params) {
             SenderId: parsed.sessionId,
             Provider: "xiaoyi-channel",
             Surface: "xiaoyi-channel",
-            MessageSid: parsed.messageId,
+            MessageSid: `xiaoyi_${parsed.taskId}_${deviceType}`,
             Timestamp: Date.now(),
             WasMentioned: false,
             CommandAuthorized: true,
@@ -242,9 +279,11 @@ export async function handleXYMessage(params) {
             ReplyToBody: undefined, // A2A protocol doesn't support reply/quote
             ...mediaPayload,
         });
-        // 🔑 创建dispatcher（dispatcher会自动使用动态taskId）
-        log(`[BOT-DISPATCHER] 🎯 Creating reply dispatcher`);
-        log(`[BOT-DISPATCHER]   - taskId: ${parsed.taskId}`);
+        // 🔑 Streaming 信号已在上方创建（在文件下载之前）
+        const steerState = { steered: false };
+        // 🔑 创建dispatcher
+        logger.log(`[BOT-DISPATCHER] 🎯 Creating reply dispatcher`);
+        logger.log(`[BOT-DISPATCHER]   - taskId: ${parsed.taskId}`);
         const { dispatcher, replyOptions, markDispatchIdle, startStatusInterval } = createXYReplyDispatcher({
             cfg,
             runtime,
@@ -252,13 +291,11 @@ export async function handleXYMessage(params) {
             taskId: parsed.taskId,
             messageId: parsed.messageId,
             accountId: route.accountId,
-            isSteerFollower: isSecondMessage, // 🔑 标记第二条消息
+            steerState,
         });
-        // 🔑 只有第一条消息启动状态定时器
-        // 第二条消息会很快返回，不需要定时器
-        if (!isSecondMessage) {
+        // Steer injections don't need status intervals
+        if (!skipReg) {
             startStatusInterval();
-            log(`[BOT-DISPATCHER] ✅ Status interval started for first message`);
         }
         // Build session context for AsyncLocalStorage
         const sessionContext = {
@@ -269,69 +306,75 @@ export async function handleXYMessage(params) {
             agentId: route.accountId,
             deviceType,
         };
-        log(`[BOT-DISPATCH] ⏳ withReplyDispatcher starting, sessionKey=${route.sessionKey}`);
+        logger.log(`[BOT-DISPATCH] ⏳ withReplyDispatcher starting, sessionKey=${route.sessionKey}`);
         await core.channel.reply.withReplyDispatcher({
             dispatcher,
             onSettled: () => {
-                log(`[BOT] 🏁 onSettled called for session: ${route.sessionKey}`);
-                log(`[BOT]   - isSecondMessage: ${isSecondMessage}`);
-                // 🔑 减少引用计数
-                decrementTaskIdRef(parsed.sessionId);
-                // 🔑 如果是第一条消息完成，解锁
-                if (!isSecondMessage) {
-                    unlockTaskId(parsed.sessionId);
-                    log(`[BOT] 🔓 Unlocked taskId (first message completed)`);
+                logger.log(`[BOT] 🏁 onSettled called for session: ${route.sessionKey}`);
+                logger.log(`[BOT]   - steered: ${steerState.steered}`);
+                // 🔑 When steered, skip heavy cleanup — the first message's dispatcher is still running
+                if (steerState.steered) {
+                    logger.log(`[BOT] ✅ Steered dispatch settled (skipping cleanup)`);
+                    return;
                 }
-                // 减少session引用计数
+                streamingSignals.delete(parsed.sessionId);
+                decrementTaskIdRef(parsed.sessionId);
                 unregisterSession(route.sessionKey);
-                log(`[BOT] ✅ Cleanup completed`);
+                logger.log(`[BOT] ✅ Cleanup completed`);
+            },
+            run: () => {
+                // 🔐 Use AsyncLocalStorage to provide session context to tools.
+                // runWithSessionContext returns after the sync part of dispatch
+                // (including agentTools + wrapStreamFn) has executed, so we
+                // signal init complete to release the global dispatch gate
+                // for the next session.
+                const dispatchPromise = runWithSessionContext(sessionContext, async () => {
+                    logger.log(`[BOT-DISPATCH] ⏳ dispatchReplyFromConfig starting...`);
+                    logger.log(`[BOT-DISPATCH]   - sessionKey: ${ctxPayload.SessionKey}`);
+                    logger.log(`[BOT-DISPATCH]   - provider: ${ctxPayload.Provider}`);
+                    logger.log(`[BOT-DISPATCH]   - surface: ${ctxPayload.Surface}`);
+                    logger.log(`[BOT-DISPATCH]   - from: ${ctxPayload.From}`);
+                    logger.log(`[BOT-DISPATCH]   - body length: ${ctxPayload.Body?.length ?? 0}`);
+                    try {
+                        const result = await core.channel.reply.dispatchReplyFromConfig({
+                            ctx: ctxPayload,
+                            cfg,
+                            dispatcher,
+                            replyOptions,
+                        });
+                        logger.log(`[BOT-DISPATCH] ✅ dispatchReplyFromConfig returned`);
+                        logger.log(`[BOT-DISPATCH]   - result: ${JSON.stringify(result)}`);
+                        return result;
+                    }
+                    catch (dispatchErr) {
+                        logger.error(`[BOT-DISPATCH] ❌ dispatchReplyFromConfig threw`);
+                        logger.error(`[BOT-DISPATCH]   - error name: ${dispatchErr instanceof Error ? dispatchErr.name : "unknown"}`);
+                        logger.error(`[BOT-DISPATCH]   - error message: ${String(dispatchErr)}`);
+                        logger.error(`[BOT-DISPATCH]   - error stack: ${dispatchErr instanceof Error ? dispatchErr.stack?.slice(0, 500) : "N/A"}`);
+                        throw dispatchErr;
+                    }
+                });
+                // Signal init complete — sync part (agentTools, wrapStreamFn) is done
+                params.onInitComplete?.();
+                return dispatchPromise;
             },
-            run: () => 
-            // 🔐 Use AsyncLocalStorage to provide session context to tools
-            runWithSessionContext(sessionContext, async () => {
-                log(`[BOT-DISPATCH] ⏳ dispatchReplyFromConfig starting...`);
-                log(`[BOT-DISPATCH]   - sessionKey: ${ctxPayload.SessionKey}`);
-                log(`[BOT-DISPATCH]   - provider: ${ctxPayload.Provider}`);
-                log(`[BOT-DISPATCH]   - surface: ${ctxPayload.Surface}`);
-                log(`[BOT-DISPATCH]   - from: ${ctxPayload.From}`);
-                log(`[BOT-DISPATCH]   - body length: ${ctxPayload.Body?.length ?? 0}`);
-                try {
-                    const result = await core.channel.reply.dispatchReplyFromConfig({
-                        ctx: ctxPayload,
-                        cfg,
-                        dispatcher,
-                        replyOptions,
-                    });
-                    log(`[BOT-DISPATCH] ✅ dispatchReplyFromConfig returned`);
-                    log(`[BOT-DISPATCH]   - result: ${JSON.stringify(result)}`);
-                    return result;
-                }
-                catch (dispatchErr) {
-                    error(`[BOT-DISPATCH] ❌ dispatchReplyFromConfig threw`);
-                    error(`[BOT-DISPATCH]   - error name: ${dispatchErr instanceof Error ? dispatchErr.name : "unknown"}`);
-                    error(`[BOT-DISPATCH]   - error message: ${String(dispatchErr)}`);
-                    error(`[BOT-DISPATCH]   - error stack: ${dispatchErr instanceof Error ? dispatchErr.stack?.slice(0, 500) : "N/A"}`);
-                    throw dispatchErr;
-                }
-            }),
         });
-        log(`[BOT] ✅ Dispatcher completed for session: ${parsed.sessionId}`);
-        log(`xy: dispatch complete (session=${parsed.sessionId})`);
+        logger.log(`[BOT] ✅ Dispatcher completed for session: ${parsed.sessionId}`);
+        logger.log(`xy: dispatch complete (session=${parsed.sessionId})`);
     }
     catch (err) {
         // ✅ Only log error, don't re-throw to prevent gateway restart
-        error("Failed to handle XY message:", err);
+        logger.error("Failed to handle XY message:", err);
         runtime.error?.(`xy: Failed to handle message: ${String(err)}`);
-        log(`[BOT] ❌ Error occurred, attempting cleanup...`);
+        logger.log(`[BOT] ❌ Error occurred, attempting cleanup...`);
         // 🔑 错误时也要清理taskId和session
         try {
             const params = message.params;
             const sessionId = params?.sessionId;
             if (sessionId) {
-                log(`[BOT] 🧹 Cleaning up after error: ${sessionId}`);
+                logger.log(`[BOT] 🧹 Cleaning up after error: ${sessionId}`);
                 // 清理 taskId
                 decrementTaskIdRef(sessionId);
-                unlockTaskId(sessionId);
                 // 清理 session
                 const core = getXYRuntime();
                 const route = core.channel.routing.resolveAgentRoute({
@@ -344,11 +387,11 @@ export async function handleXYMessage(params) {
                     },
                 });
                 unregisterSession(route.sessionKey);
-                log(`[BOT] ✅ Cleanup completed after error`);
+                logger.log(`[BOT] ✅ Cleanup completed after error`);
             }
         }
         catch (cleanupErr) {
-            log(`[BOT] ⚠️  Cleanup failed:`, cleanupErr);
+            logger.log(`[BOT] ⚠️  Cleanup failed:`, cleanupErr);
             // Ignore cleanup errors
         }
         // ❌ Don't re-throw: message processing error should not affect gateway stability
@@ -371,3 +414,169 @@ function buildXYMediaPayload(mediaList) {
         MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
     };
 }
+// Use globalThis to survive module deduplication — provider.ts may load a
+// different copy of bot.ts, so a plain module-level Map would be two objects.
+const _g = globalThis;
+if (!_g.__xyStreamingSignals)
+    _g.__xyStreamingSignals = new Map();
+if (!_g.__xySteerQueues)
+    _g.__xySteerQueues = new Map();
+const streamingSignals = _g.__xyStreamingSignals;
+const steerQueues = _g.__xySteerQueues;
+/**
+ * 由 provider.ts 在 wrapStreamFn 调用时触发。
+ * 这是模型 API 被调用的精确时刻，此时 isStreaming 一定为 true。
+ */
+export function notifyModelStreaming(sessionId) {
+    const signal = streamingSignals.get(sessionId);
+    if (signal) {
+        // 不删除 signal——后续 steer 需要靠它判断模型已在 streaming。
+        // 清理由第一条消息的 onSettled 兜底。
+        signal.notify();
+        logger.log(`[STEER-QUEUE] 📡 Model streaming signal fired for session=${sessionId}`);
+    }
+}
+function createStreamingSignal(sessionId) {
+    let resolve;
+    const promise = new Promise(r => { resolve = r; });
+    const signal = { promise, notify: resolve };
+    streamingSignals.set(sessionId, signal);
+    logger.log(`[STEER-QUEUE] 🟢 Streaming signal created for session ${sessionId}`);
+    return signal;
+}
+/**
+ * 将 steer 消息放入 per-session 串行队列。
+ * 等待第一条消息的 streaming 信号（deliver 首次触发），然后 dispatch。
+ * 多个 steer 按到达顺序串行处理，无需重试。
+ */
+function enqueueSteer(params) {
+    const { sessionId } = params;
+    // 取出当前队列尾部（或 undefined），然后链上新的 Promise
+    const prev = steerQueues.get(sessionId);
+    const next = (prev ?? Promise.resolve()).then(() => dispatchSteerWhenReady(params));
+    steerQueues.set(sessionId, next);
+    // 链条结束后清理
+    next.catch((err) => {
+        logger.error(`[STEER-QUEUE] ❌ Steer chain failed: ${String(err)}`);
+    }).finally(() => {
+        if (steerQueues.get(sessionId) === next) {
+            steerQueues.delete(sessionId);
+        }
+    });
+    return next;
+}
+async function dispatchSteerWhenReady(params) {
+    const { sessionId, sessionKey, steerText } = params;
+    // 1. 等待第一条消息开始 streaming
+    //    signal 可能尚未创建（第一条消息还在文件下载等耗时操作中），
+    //    轮询等待直到 signal 出现，最長等待 ~5 秒。
+    let signal = streamingSignals.get(sessionId);
+    if (!signal) {
+        logger.log(`[STEER-QUEUE] ⏳ Signal not yet created, polling for session=${sessionId}`);
+        for (let i = 0; i < 50; i++) {
+            await new Promise(r => setTimeout(r, 100));
+            signal = streamingSignals.get(sessionId);
+            if (signal)
+                break;
+            if (!hasActiveTask(sessionId)) {
+                logger.log(`[STEER-QUEUE] ℹ️ First message completed while waiting, skip steer`);
+                return;
+            }
+        }
+    }
+    if (signal) {
+        logger.log(`[STEER-QUEUE] ⏳ Waiting for streaming signal, session=${sessionId}`);
+        await signal.promise;
+        logger.log(`[STEER-QUEUE] ✅ Streaming signal received, session=${sessionId}`);
+    }
+    else {
+        // 轮询超时且 hasActiveTask 仍为 true——说明第一条消息可能卡在异常路径，
+        // 没有创建 signal。此时 dispatch 会与第一条消息的模型调用并发冲突，放弃。
+        logger.log(`[STEER-QUEUE] ⚠️ Signal never appeared after polling, skip steer to avoid collision`);
+        return;
+    }
+    // 2. 第一条消息已结束 → 放弃
+    if (!hasActiveTask(sessionId)) {
+        logger.log(`[STEER-QUEUE] ℹ️ First message completed, skip steer`);
+        return;
+    }
+    // 3. 构建 dispatch 上下文并 dispatch /steer
+    const core = getXYRuntime();
+    const speaker = sessionId;
+    // 如果有文件附件，把路径拼到 steer 文本末尾，让模型通过工具读取
+    const mediaPaths = params.mediaPayload?.MediaPaths;
+    const fileHint = mediaPaths && mediaPaths.length > 0
+        ? `\n【用户上传附件】：${JSON.stringify(mediaPaths)}`
+        : "";
+    const steerCommand = `/steer ${steerText}${fileHint}`;
+    const messageBody = `${speaker}: ${steerCommand}`;
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(params.cfg);
+    const body = core.channel.reply.formatAgentEnvelope({
+        channel: "xiaoyi-channel",
+        from: speaker,
+        timestamp: new Date(),
+        envelope: envelopeOptions,
+        body: messageBody,
+    });
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: steerCommand,
+        CommandBody: steerCommand,
+        From: sessionId,
+        To: sessionId,
+        SessionKey: params.route.sessionKey,
+        AccountId: params.route.accountId,
+        ChatType: "direct",
+        GroupSubject: undefined,
+        SenderName: sessionId,
+        SenderId: sessionId,
+        Provider: "xiaoyi-channel",
+        Surface: "xiaoyi-channel",
+        MessageSid: `xiaoyi_${params.parsed.taskId}_${params.deviceType}`,
+        Timestamp: Date.now(),
+        WasMentioned: false,
+        CommandAuthorized: true,
+        OriginatingChannel: "xiaoyi-channel",
+        OriginatingTo: sessionId,
+        ReplyToBody: undefined,
+        ...params.mediaPayload,
+    });
+    const steerState = { steered: true };
+    const { dispatcher, replyOptions } = createXYReplyDispatcher({
+        cfg: params.cfg,
+        runtime: params.runtime,
+        sessionId,
+        taskId: params.parsed.taskId,
+        messageId: params.parsed.messageId,
+        accountId: params.route.accountId,
+        steerState,
+    });
+    const sessionContext = {
+        config: resolveXYConfig(params.cfg),
+        sessionId,
+        taskId: params.parsed.taskId,
+        messageId: params.parsed.messageId,
+        agentId: params.route.accountId,
+        deviceType: params.deviceType,
+    };
+    logger.log(`[STEER-QUEUE] 🚀 Dispatching steer for session=${sessionId}`);
+    await core.channel.reply.withReplyDispatcher({
+        dispatcher,
+        onSettled: () => {
+            logger.log(`[STEER-QUEUE] 🏁 Steer dispatch settled for session=${sessionId}`);
+        },
+        run: () => {
+            return runWithSessionContext(sessionContext, async () => {
+                const result = await core.channel.reply.dispatchReplyFromConfig({
+                    ctx: ctxPayload,
+                    cfg: params.cfg,
+                    dispatcher,
+                    replyOptions,
+                });
+                logger.log(`[STEER-QUEUE] dispatch result: ${JSON.stringify(result)}`);
+                return result;
+            });
+        },
+    });
+    logger.log(`[STEER-QUEUE] ✅ Steer dispatch completed for session=${sessionId}`);
+}