@ynhcj/xiaoyi-channel 0.0.222-next → 0.0.223-next

package/dist/index.js

@@ -15,7 +15,8 @@ import { normalizeToolRetrieverConfig } from "./src/skill-retriever/config.js";
 import { registerCLIHook } from "./src/tools/hmos-cli.js";
 import { recoverCronState } from "./src/cron-recovery.js";
 import { writeSkillUsage } from "./src/utils/skills-logger.js";
-import { markSubagentSpawned, markSubagentEnded, getCachedXYConfig, } from "./src/subagent-wait-state.js";
+import { markSubagentSpawned, markSubagentEnded, deliverSubagentFinalResult, } from "./src/conversation/conversation-manager.js";
+import { notifyCronAgentEnd } from "./src/conversation/cron-buffer.js";
 import { logger } from "./src/utils/logger.js";
 /**
  * Parse a file path string to detect if it refers to a SKILL.md file within
@@ -56,6 +57,7 @@ function registerSkillsDiagnosticHook(api) {
         message: "message",
         get_phone_tool_schema: "phone",
         get_collection_tool_schema: "xiaoyi-collection",
+        image_reading: "xiaoyi-image-understanding"
     };
     // Log skill usage for known device tools on before_tool_call
     api.on("before_tool_call", async (event, _ctx) => {
@@ -330,15 +332,8 @@ function registerSubagentHooks(api) {
             logger.log(`[XY-SUBAGENT-END] ended, targetSessionKey=${event?.targetSessionKey?.slice(0, 30)}, outcome=${event?.outcome}, complete=${transition?.isComplete ?? false}, shouldFinalize=${transition?.shouldFinalize ?? false}, transition=${!!transition}`);
             if (transition?.shouldFinalize) {
                 logger.log(`[XY-SUBAGENT-END] Starting finalization...`);
-                const config = getCachedXYConfig();
-                if (!config) {
-                    logger.error(`[XY-SUBAGENT-END] No cached XY config, cannot deliver final result`);
-                    return;
-                }
-                const { deliverSubagentFinalResult } = await import("./src/outbound.js");
-                logger.log(`[XY-SUBAGENT-END] Using cached XY config`);
+                // 最终交付由对话管理层统一负责（含 config 解析、final 帧、清理）
                 await deliverSubagentFinalResult({
-                    config: config,
                     state: transition.state,
                     reason: "all-subagents-ended-after-parent-settled",
                 });
@@ -353,6 +348,33 @@ function registerSubagentHooks(api) {
 function registerFullHooks(api) {
     // SUBAGENT HOOKS: track subagent spawn/end lifecycle for session keep-alive
     registerSubagentHooks(api);
+    // CRON AGGREGATION: 通过 agent 事件总线感知 cron isolated run 结束。
+    // 注意：agent_end 插件 hook 只在 dispatch-from-config 路径触发，cron
+    // isolated run 不会触发它；embedded run 的 lifecycle 事件才是可靠信号。
+    // phase=end/error 后到达的 sendText 即为 announce 最终结果（放行）。
+    api.agent.events.registerAgentEventSubscription({
+        id: "xy-cron-turn-tracker",
+        description: "Track cron isolated run completion for sendText aggregation",
+        streams: ["lifecycle"],
+        handle: (event) => {
+            try {
+                const phase = event?.data?.phase;
+                // 仅 phase=end 是 run 级终态信号；phase=error 可能是单次模型调用
+                // 失败（后续还有重试/start），不能据此放行 announce。
+                // 真正失败的 run（无 end）由 120s 安全超时兜底 flush 缓冲文本。
+                if (phase !== "end")
+                    return;
+                const sessionKey = event?.sessionKey ?? "";
+                if (sessionKey.startsWith("cron:") || sessionKey.includes(":cron:") || isCronActive()) {
+                    logger.log(`[XY-CRON] Cron run lifecycle end, sessionKey=${sessionKey || "unknown"}`);
+                    notifyCronAgentEnd();
+                }
+            }
+            catch (err) {
+                logger.error(`[XY-CRON] Error in cron lifecycle subscription:`, err);
+            }
+        },
+    });
     // SKILL RETRIEVER HOOK: before_prompt_build hook
     const pluginConfig = api.pluginConfig || {};
     const skillRetrieverConfig = normalizeToolRetrieverConfig({

package/dist/src/bot.js

@@ -313,7 +313,7 @@ export async function handleXYMessage(params) {
         // per-session ReplyOperation lock in admitReplyTurn which would otherwise
         // block the steer message until the first message completes — making steer
         // indistinguishable from a followup.
-        if (isUpdate && !skipReg && route.sessionKey) {
+        if (isUpdate && route.sessionKey) {
             const activeSessionId = resolveActiveEmbeddedRunSessionId(route.sessionKey);
             if (activeSessionId) {
                 log.log(`[BOT-STEER] Direct steer attempt: activeSessionId=${activeSessionId}, textLen=${textForAgent.length}`);
@@ -486,7 +486,7 @@ export async function handleXYMessage(params) {
                 // signal init complete to release the global dispatch gate
                 // for the next session.
                 const dispatchPromise = runWithSessionContext(sessionContext, async () => {
-                    const isSteerDispatch = isUpdate && !skipReg;
+                    const isSteerDispatch = isUpdate;
                     log.log(`[ALS-PROOF] bot entered dispatch scope sessionId=${sessionContext.sessionId} taskId=${sessionContext.taskId} isSteer=${isSteerDispatch}`);
                     log.log(`[BOT-DISPATCH] dispatchReplyFromConfig starting, body.length=${ctxPayload.Body?.length ?? 0}`);
                     try {

package/dist/src/channel.js

@@ -1,6 +1,6 @@
 import { resolveXYConfig, listXYAccountIds, getDefaultXYAccountId } from "./config.js";
 import { xyConfigSchema } from "./config-schema.js";
-import { xyOutbound } from "./outbound.js";
+import { xyOutbound } from "./dispatch/outbound.js";
 import { filterToolsByDevice } from "./tools/device-tool-map.js";
 import { getCurrentSessionContext } from "./tools/session-manager.js";
 import { logger } from "./utils/logger.js";
@@ -158,7 +158,7 @@ export const xyPlugin = {
     },
     gateway: {
         async startAccount(context) {
-            const { monitorXYProvider } = await import("./monitor.js");
+            const { monitorXYProvider } = await import("./dispatch/monitor.js");
             const { createXyAcpBindingManager } = await import("./acp-session-binding.js");
             const account = resolveXYConfig(context.cfg);
             context.setStatus?.({

package/dist/src/conversation/conversation-manager.d.ts

@@ -0,0 +1,87 @@
+import { ConversationSession, SubagentWaitState, SubagentWaitTransition, TaskEntry } from "./conversation-session.js";
+export declare function getOrCreateSession(sessionId: string): ConversationSession;
+export declare function getSession(sessionId: string): ConversationSession | null;
+export declare function deleteSession(sessionId: string): void;
+export declare function listSessions(): ConversationSession[];
+/** 会话状态迁移（working / waiting-subagent / completing / 终态）。 */
+export declare function setSessionState(sessionId: string, state: ConversationSession["state"]): void;
+/**
+ * 注册或更新 session 的活跃 taskId。
+ * Returns true if this was an update (session already had an active task).
+ */
+export declare function registerTask(sessionId: string, taskId: string, messageId: string): boolean;
+/**
+ * 移除 session 的活跃 taskId（消息处理完成时调用）。
+ * @param expectedTaskId 可选：精确移除指定的 taskId，而非清空整个任务链。
+ */
+export declare function completeTask(sessionId: string, expectedTaskId?: string): void;
+/** 获取 session 当前活跃 task（任务链末尾）。 */
+export declare function getCurrentTask(sessionId: string): TaskEntry | null;
+/** 获取 session 当前活跃 taskId（reply-dispatcher 跨链读取 / 工具富化用）。 */
+export declare function getCurrentTaskId(sessionId: string): string | null;
+/** 获取 session 当前活跃 messageId。 */
+export declare function getCurrentMessageId(sessionId: string): string | null;
+export declare function hasActiveTask(sessionId: string): boolean;
+/** 所有活跃 task 绑定（gateway_stop 通知等场景）。 */
+export declare function listActiveTaskBindings(): Array<{
+    sessionId: string;
+    currentTaskId: string;
+    currentMessageId: string;
+    updatedAt: number;
+}>;
+/**
+ * 绑定 openclaw sessionKey 到首条消息的 A2A 身份。
+ * 仅在首条消息时调用（steer 消息不覆盖，保持 subagent 等待态跟踪稳定）。
+ */
+export declare function bindSessionKey(sessionKey: string, sessionId: string, taskId: string, messageId: string): void;
+export declare function resolveBySessionKey(sessionKey: string): {
+    sessionId: string;
+    taskId: string;
+    messageId: string;
+} | null;
+export declare function unbindSessionKey(sessionKey: string): void;
+/**
+ * 全局缓存 resolved XY config，供 hook 上下文（无 raw ClawdbotConfig）使用。
+ */
+export declare function cacheXYConfig(config: unknown): void;
+export declare function getCachedXYConfig(): unknown;
+/**
+ * 启动（或重启）session 的 30s 状态心跳。
+ * 心跳由 manager 拥有：dispatcher 销毁不影响心跳；
+ * tick 时读取任务链末尾的当前 taskId/messageId。
+ */
+export declare function startStatusHeartbeat(sessionId: string, text?: string): void;
+export declare function stopStatusHeartbeat(sessionId: string): void;
+/**
+ * subagent_spawned hook 调用。递增 expected completion 计数。
+ * 若等待态尚不存在则创建（sessions_spawn 可能先于 sessions_yield）。
+ */
+export declare function markSubagentSpawned(sessionKey: string): number;
+/**
+ * subagent_ended hook 调用。标记一个 subagent run 结束并计为一次交付。
+ * 这是主要的完成跟踪机制（subagent 完成可能不经 xyOutbound.sendText）。
+ */
+export declare function markSubagentEnded(sessionKey: string): SubagentWaitTransition | null;
+/**
+ * bot.ts onSettled 调用。标记父 dispatcher 已 settle。
+ */
+export declare function markParentSettled(sessionId: string, taskId: string): SubagentWaitTransition | null;
+/**
+ * 存储从 xyOutbound.sendText 捕获的完成文本。不递增交付计数。
+ */
+export declare function addCompletionText(sessionId: string, taskId: string, text: string): void;
+export declare function getWaitState(sessionId: string, taskId?: string): SubagentWaitState | null;
+export declare function hasWaitState(sessionId: string, taskId?: string): boolean;
+export declare function clearWaitState(sessionId: string, reason: string, taskId?: string): SubagentWaitState | null;
+/**
+ * 当所有 subagent 完成且父 turn 已 settle 时，由 manager 发送唯一的
+ * final 帧并真正结束当前 A2A session：
+ *   1. 合并 completionTexts 发送 final:true 帧
+ *   2. 清理等待态、停止心跳、移除任务链
+ *   3. 会话状态迁移到 completed
+ */
+export declare function deliverSubagentFinalResult(params: {
+    state: SubagentWaitState;
+    reason?: string;
+    text?: string;
+}): Promise<void>;

package/dist/src/conversation/conversation-manager.js

@@ -0,0 +1,387 @@
+// 对话管理层 —— ConversationManager。
+//
+// 收拢 openclaw 与 xy server 之间的会话状态与生命周期管理：
+//   - session 注册表（globalThis 单例，跨模块去重存活）
+//   - task 身份链（吸收自原 task-manager.ts）
+//   - sessionKey ↔ sessionId 索引（吸收自原 subagent-wait-state.ts 的 sessionKeyMap）
+//   - subagent 等待态（吸收自原 subagent-wait-state.ts）
+//   - XY config 缓存（吸收自原 __xyCachedXYConfig）
+//
+// 依赖方向约束：本模块只允许依赖 conversation-session / utils / types，
+// 禁止 import dispatch 层（bot/reply-dispatcher/monitor/outbound），避免循环。
+import { randomUUID } from "crypto";
+import { logger } from "../utils/logger.js";
+import { sendStatusUpdate, sendA2AResponse } from "../formatter.js";
+import { createConversationSession, } from "./conversation-session.js";
+// ─── Global registry（globalThis 单例） ───────────────────────
+const _g = globalThis;
+if (!_g.__xyConversationSessions) {
+    _g.__xyConversationSessions = new Map();
+}
+if (!_g.__xySessionKeyIndex) {
+    // sessionKey → 首条消息的 { sessionId, taskId, messageId }。
+    // 注意：taskId/messageId 刻意保留首条消息的值（steer 消息不覆盖），
+    // 与原 registerSessionKeyMapping 语义一致。
+    _g.__xySessionKeyIndex = new Map();
+}
+if (!_g.__xyConversationCachedConfig) {
+    _g.__xyConversationCachedConfig = null;
+}
+const sessions = _g.__xyConversationSessions;
+const sessionKeyIndex = _g.__xySessionKeyIndex;
+// ─── Session registry ─────────────────────────────────────────
+export function getOrCreateSession(sessionId) {
+    let session = sessions.get(sessionId);
+    if (!session) {
+        session = createConversationSession(sessionId);
+        sessions.set(sessionId, session);
+    }
+    session.lastActivityAt = Date.now();
+    return session;
+}
+export function getSession(sessionId) {
+    return sessions.get(sessionId) ?? null;
+}
+export function deleteSession(sessionId) {
+    sessions.delete(sessionId);
+}
+export function listSessions() {
+    return Array.from(sessions.values());
+}
+/** 会话状态迁移（working / waiting-subagent / completing / 终态）。 */
+export function setSessionState(sessionId, state) {
+    const session = sessions.get(sessionId);
+    if (session) {
+        session.state = state;
+        session.lastActivityAt = Date.now();
+    }
+}
+// ─── Task 身份链（吸收自原 task-manager.ts） ──────────────────
+/**
+ * 注册或更新 session 的活跃 taskId。
+ * Returns true if this was an update (session already had an active task).
+ */
+export function registerTask(sessionId, taskId, messageId) {
+    const session = getOrCreateSession(sessionId);
+    const isUpdate = session.tasks.length > 0;
+    if (isUpdate) {
+        logger.log(`[TASK_MANAGER] Updating taskId: ${session.tasks[session.tasks.length - 1].taskId} → ${taskId}`);
+    }
+    else {
+        logger.log(`[TASK_MANAGER] Registered new taskId: ${taskId}`);
+    }
+    session.tasks = session.tasks.filter((entry) => entry.taskId !== taskId);
+    session.tasks.push({ taskId, messageId, updatedAt: Date.now() });
+    return isUpdate;
+}
+/**
+ * 移除 session 的活跃 taskId（消息处理完成时调用）。
+ * @param expectedTaskId 可选：精确移除指定的 taskId，而非清空整个任务链。
+ */
+export function completeTask(sessionId, expectedTaskId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return;
+    if (!expectedTaskId) {
+        logger.log(`[TASK_MANAGER] Removing taskId`);
+        session.tasks = [];
+        return;
+    }
+    const nextTasks = session.tasks.filter((entry) => entry.taskId !== expectedTaskId);
+    if (nextTasks.length === session.tasks.length) {
+        const current = session.tasks[session.tasks.length - 1];
+        logger.log(`[TASK_MANAGER] Preserving taskId ${current?.taskId}; completed task ${expectedTaskId} is not active`);
+        return;
+    }
+    session.tasks = nextTasks;
+    if (nextTasks.length > 0) {
+        logger.log(`[TASK_MANAGER] Removed taskId ${expectedTaskId}, restored current taskId ${nextTasks[nextTasks.length - 1].taskId}`);
+    }
+    else {
+        logger.log(`[TASK_MANAGER] Removing taskId (last task ${expectedTaskId})`);
+    }
+}
+/** 获取 session 当前活跃 task（任务链末尾）。 */
+export function getCurrentTask(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session || session.tasks.length === 0)
+        return null;
+    return session.tasks[session.tasks.length - 1];
+}
+/** 获取 session 当前活跃 taskId（reply-dispatcher 跨链读取 / 工具富化用）。 */
+export function getCurrentTaskId(sessionId) {
+    return getCurrentTask(sessionId)?.taskId ?? null;
+}
+/** 获取 session 当前活跃 messageId。 */
+export function getCurrentMessageId(sessionId) {
+    return getCurrentTask(sessionId)?.messageId ?? null;
+}
+export function hasActiveTask(sessionId) {
+    const session = sessions.get(sessionId);
+    return !!session && session.tasks.length > 0;
+}
+/** 所有活跃 task 绑定（gateway_stop 通知等场景）。 */
+export function listActiveTaskBindings() {
+    const result = [];
+    for (const session of sessions.values()) {
+        const current = session.tasks[session.tasks.length - 1];
+        if (current) {
+            result.push({
+                sessionId: session.sessionId,
+                currentTaskId: current.taskId,
+                currentMessageId: current.messageId,
+                updatedAt: current.updatedAt,
+            });
+        }
+    }
+    return result;
+}
+// ─── SessionKey ↔ SessionId 索引 ──────────────────────────────
+/**
+ * 绑定 openclaw sessionKey 到首条消息的 A2A 身份。
+ * 仅在首条消息时调用（steer 消息不覆盖，保持 subagent 等待态跟踪稳定）。
+ */
+export function bindSessionKey(sessionKey, sessionId, taskId, messageId) {
+    if (!sessionKey || !sessionId)
+        return;
+    sessionKeyIndex.set(sessionKey, { sessionId, taskId, messageId });
+    const session = getOrCreateSession(sessionId);
+    session.sessionKey = sessionKey;
+}
+export function resolveBySessionKey(sessionKey) {
+    return sessionKeyIndex.get(sessionKey) ?? null;
+}
+export function unbindSessionKey(sessionKey) {
+    sessionKeyIndex.delete(sessionKey);
+}
+// ─── XY config 缓存 ───────────────────────────────────────────
+/**
+ * 全局缓存 resolved XY config，供 hook 上下文（无 raw ClawdbotConfig）使用。
+ */
+export function cacheXYConfig(config) {
+    _g.__xyConversationCachedConfig = config;
+}
+export function getCachedXYConfig() {
+    return _g.__xyConversationCachedConfig;
+}
+// ─── 30s 状态心跳（manager 拥有，独立于 dispatcher 生命周期） ──
+const STATUS_HEARTBEAT_INTERVAL_MS = 30 * 1000;
+const DEFAULT_STATUS_TEXT = "任务正在处理中，请稍候~";
+/**
+ * 启动（或重启）session 的 30s 状态心跳。
+ * 心跳由 manager 拥有：dispatcher 销毁不影响心跳；
+ * tick 时读取任务链末尾的当前 taskId/messageId。
+ */
+export function startStatusHeartbeat(sessionId, text = DEFAULT_STATUS_TEXT) {
+    const session = getOrCreateSession(sessionId);
+    if (session.statusTimer) {
+        clearInterval(session.statusTimer);
+    }
+    logger.withContext(sessionId, "").log(`[STATUS-HEARTBEAT] Starting manager-owned heartbeat, text="${text}"`);
+    session.statusTimer = setInterval(() => {
+        const current = getCurrentTask(sessionId);
+        const config = getCachedXYConfig();
+        if (!current || !config) {
+            return;
+        }
+        void sendStatusUpdate({
+            config,
+            sessionId,
+            taskId: current.taskId,
+            messageId: current.messageId,
+            text,
+            state: "working",
+        }).catch((err) => {
+            logger.withContext(sessionId, current.taskId).error(`Failed to send status update:`, err);
+        });
+    }, STATUS_HEARTBEAT_INTERVAL_MS);
+}
+export function stopStatusHeartbeat(sessionId) {
+    const session = sessions.get(sessionId);
+    if (session?.statusTimer) {
+        logger.withContext(sessionId, "").log(`[STATUS-HEARTBEAT] Stopping manager-owned heartbeat`);
+        clearInterval(session.statusTimer);
+        session.statusTimer = undefined;
+    }
+}
+// ─── Subagent 等待态（吸收自原 subagent-wait-state.ts） ───────
+const WAIT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+function isExpired(state) {
+    return Date.now() - state.startedAt > WAIT_TTL_MS;
+}
+function isComplete(state) {
+    return state.deliveredCompletions >= Math.max(1, state.expectedCompletions);
+}
+function claimFinalizationIfReady(state) {
+    if (state.finalizationClaimed)
+        return false;
+    if (!state.parentSettled || !isComplete(state))
+        return false;
+    state.finalizationClaimed = true;
+    return true;
+}
+function getStatesArray(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return [];
+    const active = session.subagentWaits.filter((s) => {
+        if (!isExpired(s))
+            return true;
+        stopStatusHeartbeat(sessionId);
+        logger.withContext(sessionId, s.taskId).log(`[SUBAGENT-WAIT] Expired wait state cleared, expected=${s.expectedCompletions}, delivered=${s.deliveredCompletions}`);
+        return false;
+    });
+    session.subagentWaits = active;
+    return active;
+}
+/**
+ * subagent_spawned hook 调用。递增 expected completion 计数。
+ * 若等待态尚不存在则创建（sessions_spawn 可能先于 sessions_yield）。
+ */
+export function markSubagentSpawned(sessionKey) {
+    const mapped = resolveBySessionKey(sessionKey);
+    if (!mapped) {
+        logger.log(`[SUBAGENT-WAIT] No session mapping for sessionKey=${sessionKey.slice(0, 30)}`);
+        return 0;
+    }
+    const { sessionId, taskId, messageId } = mapped;
+    const session = getOrCreateSession(sessionId);
+    const states = getStatesArray(sessionId);
+    let state = states.find((s) => s.taskId === taskId);
+    if (!state) {
+        state = {
+            sessionId,
+            sessionKey,
+            taskId,
+            messageId,
+            artifactId: randomUUID(),
+            startedAt: Date.now(),
+            expectedCompletions: 0,
+            deliveredCompletions: 0,
+            completionTexts: [],
+            parentSettled: false,
+            finalizationClaimed: false,
+        };
+        states.push(state);
+    }
+    state.expectedCompletions = Math.max(1, state.expectedCompletions + 1);
+    session.subagentWaits = states;
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Subagent spawned, expected=${state.expectedCompletions}`);
+    return state.expectedCompletions;
+}
+/**
+ * subagent_ended hook 调用。标记一个 subagent run 结束并计为一次交付。
+ * 这是主要的完成跟踪机制（subagent 完成可能不经 xyOutbound.sendText）。
+ */
+export function markSubagentEnded(sessionKey) {
+    const mapped = resolveBySessionKey(sessionKey);
+    if (!mapped)
+        return null;
+    const { sessionId, taskId } = mapped;
+    const session = getOrCreateSession(sessionId);
+    const states = getStatesArray(sessionId);
+    const state = states.find((s) => s.taskId === taskId);
+    if (!state) {
+        logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Subagent ended but no wait state found`);
+        return null;
+    }
+    state.deliveredCompletions += 1;
+    const complete = isComplete(state);
+    const shouldFinalize = claimFinalizationIfReady(state);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Subagent ended, delivered=${state.deliveredCompletions}/${state.expectedCompletions}, complete=${complete}, shouldFinalize=${shouldFinalize}`);
+    return { state, isComplete: complete, shouldFinalize };
+}
+/**
+ * bot.ts onSettled 调用。标记父 dispatcher 已 settle。
+ */
+export function markParentSettled(sessionId, taskId) {
+    const session = getOrCreateSession(sessionId);
+    const states = getStatesArray(sessionId);
+    const state = states.find((s) => s.taskId === taskId);
+    if (!state) {
+        logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] No wait state matched for parent settled`);
+        return null;
+    }
+    state.parentSettled = true;
+    const complete = isComplete(state);
+    const shouldFinalize = claimFinalizationIfReady(state);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Parent settled, completions=${state.deliveredCompletions}/${state.expectedCompletions}, shouldFinalize=${shouldFinalize}`);
+    return { state, isComplete: complete, shouldFinalize };
+}
+/**
+ * 存储从 xyOutbound.sendText 捕获的完成文本。不递增交付计数。
+ */
+export function addCompletionText(sessionId, taskId, text) {
+    const states = getStatesArray(sessionId);
+    const state = states.find((s) => s.taskId === taskId);
+    if (!state || !text.trim())
+        return;
+    state.completionTexts.push(text.trim());
+}
+export function getWaitState(sessionId, taskId) {
+    const states = getStatesArray(sessionId);
+    if (states.length === 0)
+        return null;
+    if (taskId) {
+        return states.find((s) => s.taskId === taskId) ?? null;
+    }
+    // FIFO: 未指定 taskId 时返回最早的等待态
+    return states[0] ?? null;
+}
+export function hasWaitState(sessionId, taskId) {
+    return getWaitState(sessionId, taskId) !== null;
+}
+export function clearWaitState(sessionId, reason, taskId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return null;
+    const states = getStatesArray(sessionId);
+    if (states.length === 0)
+        return null;
+    const index = taskId
+        ? states.findIndex((s) => s.taskId === taskId)
+        : 0;
+    if (index < 0) {
+        logger.withContext(sessionId, taskId ?? "").log(`[SUBAGENT-WAIT] No wait state matched for clear, reason=${reason}`);
+        return null;
+    }
+    const [state] = states.splice(index, 1);
+    stopStatusHeartbeat(sessionId);
+    session.subagentWaits = states;
+    logger.withContext(sessionId, state.taskId).log(`[SUBAGENT-WAIT] Cleared wait state, reason=${reason}, remaining=${states.length}`);
+    return state;
+}
+// ─── Subagent 最终交付（收拢自原 outbound.deliverSubagentFinalResult） ──
+/**
+ * 当所有 subagent 完成且父 turn 已 settle 时，由 manager 发送唯一的
+ * final 帧并真正结束当前 A2A session：
+ *   1. 合并 completionTexts 发送 final:true 帧
+ *   2. 清理等待态、停止心跳、移除任务链
+ *   3. 会话状态迁移到 completed
+ */
+export async function deliverSubagentFinalResult(params) {
+    const { state, reason } = params;
+    const log = logger.withContext(state.sessionId, state.taskId);
+    const config = getCachedXYConfig();
+    if (!config) {
+        log.error(`[SUBAGENT-FINAL] No cached XY config, cannot deliver final result`);
+        return;
+    }
+    const finalText = state.completionTexts.length > 0
+        ? state.completionTexts.join("\n\n")
+        : (params.text || undefined) ?? "子任务已完成";
+    setSessionState(state.sessionId, "completing");
+    await sendA2AResponse({
+        config,
+        sessionId: state.sessionId,
+        taskId: state.taskId,
+        messageId: state.messageId,
+        text: finalText,
+        append: false,
+        final: true,
+    });
+    clearWaitState(state.sessionId, reason ?? "all-subagent-results-delivered", state.taskId);
+    completeTask(state.sessionId, state.taskId);
+    setSessionState(state.sessionId, "completed");
+    log.log(`[SUBAGENT-FINAL] Subagent final delivered to original A2A task, reason=${reason}`);
+}

package/dist/src/conversation/conversation-session.d.ts

@@ -0,0 +1,38 @@
+export interface TaskEntry {
+    taskId: string;
+    messageId: string;
+    updatedAt: number;
+}
+export type SessionState = "working" | "waiting-subagent" | "completing" | "completed" | "failed" | "canceled";
+export interface SubagentWaitState {
+    sessionId: string;
+    sessionKey: string;
+    taskId: string;
+    messageId: string;
+    artifactId: string;
+    startedAt: number;
+    expectedCompletions: number;
+    deliveredCompletions: number;
+    completionTexts: string[];
+    parentSettled: boolean;
+    finalizationClaimed: boolean;
+}
+export interface SubagentWaitTransition {
+    state: SubagentWaitState;
+    isComplete: boolean;
+    shouldFinalize: boolean;
+}
+export interface ConversationSession {
+    /** A2A sessionId —— 注册表 key。 */
+    sessionId: string;
+    state: SessionState;
+    /** taskId/messageId 链，最后一个为当前任务。 */
+    tasks: TaskEntry[];
+    /** openclaw 路由 sessionKey（首条消息时绑定）。 */
+    sessionKey?: string;
+    subagentWaits: SubagentWaitState[];
+    /** manager 拥有的 30s 状态心跳定时器。 */
+    statusTimer?: NodeJS.Timeout;
+    lastActivityAt: number;
+}
+export declare function createConversationSession(sessionId: string): ConversationSession;

package/dist/src/conversation/conversation-session.js

@@ -0,0 +1,17 @@
+// 对话管理层 —— 会话状态对象定义。
+//
+// ConversationSession 是对话管理层的核心状态载体，收拢了重构前散落在
+// task-manager / subagent-wait-state / reply-dispatcher 闭包中的会话状态：
+//   - tasks:        session 的 taskId/messageId 链（吸收自 task-manager）
+//   - sessionKey:   openclaw 路由 sessionKey（吸收自 sessionKeyMap）
+//   - subagentWaits: subagent 等待态（吸收自 subagent-wait-state）
+//   - statusTimer:  30s 状态心跳定时器（由 manager 拥有）
+export function createConversationSession(sessionId) {
+    return {
+        sessionId,
+        state: "working",
+        tasks: [],
+        subagentWaits: [],
+        lastActivityAt: Date.now(),
+    };
+}

package/dist/src/conversation/cron-buffer.d.ts

@@ -0,0 +1,25 @@
+import type { XYChannelConfig } from "../types.js";
+/** 关闭当前 cron turn（清理全部定时器）。 */
+export declare function closeCronTurn(reason: string): void;
+/**
+ * cron turn 开始检测。由 provider.ts 在识别到 [cron:...] 首条消息时调用。
+ * 同一 cron run 的每次模型调用都会重复触发检测 —— 此时仅刷新安全定时器，
+ * 不重开 turn（避免 churn，也避免重置 agentEnded/缓冲状态）。
+ */
+export declare function notifyCronDetected(jobId?: string): void;
+/**
+ * cron run 结束信号（lifecycle phase=end，由 index.ts 的 agent event
+ * subscription 调用）。进入 announce 宽限期：
+ *   - 宽限期内 announce 到达 → 放行（见 gateCronSendText）；
+ *   - 宽限期结束无 announce → 合并缓冲文本发一条（路径 B）。
+ */
+export declare function notifyCronAgentEnd(): void;
+export type CronSendTextGate = "swallow" | "announce" | "none";
+/**
+ * sendText 闸门：
+ * - "swallow"：cron turn 进行中（run 未结束），吞掉中间 sendText，文本入缓冲；
+ * - "announce"：run 已结束（宽限期内），当前 sendText 是 announce 最终
+ *   结果，放行（唯一一条，缓冲丢弃）；
+ * - "none"：无 cron turn，正常发送。
+ */
+export declare function gateCronSendText(swallowedText?: string, config?: XYChannelConfig): CronSendTextGate;