@ynhcj/xiaoyi-channel 0.0.187-next → 0.0.188-next

package/dist/index.js

@@ -10,6 +10,7 @@ import { getAllPushIds } from "./src/utils/pushid-manager.js";
 import { registerSelfEvolutionToolResultNudge } from "./src/self-evolution-tool-result-nudge.js";
 import { createBeforePromptBuildHandler } from "./src/skill-retriever/hooks.js";
 import { normalizeToolRetrieverConfig } from "./src/skill-retriever/config.js";
+import { markSubagentSpawned, markSubagentEnded, } from "./src/subagent-wait-state.js";
 /**
  * Register the cron detection hook.
  *
@@ -167,7 +168,32 @@ function readJobIdFromResult(result) {
     }
     return undefined;
 }
+function registerSubagentHooks(api) {
+    // subagent_spawned: fires after a subagent run is successfully registered.
+    // We increment the expected completion count so that onIdle knows to wait.
+    api.on("subagent_spawned", async (_event, ctx) => {
+        const requesterSessionKey = ctx?.requesterSessionKey;
+        if (!requesterSessionKey)
+            return;
+        const count = markSubagentSpawned(requesterSessionKey);
+        if (count > 0) {
+            console.log(`[XY-SUBAGENT] spawned, requesterSessionKey=${requesterSessionKey.slice(0, 30)}, expected=${count}`);
+        }
+    });
+    // subagent_ended: fires when a subagent run terminates (complete/error/killed).
+    // We log the event for tracking; the actual completion count is decremented
+    // when the subagent result is delivered via xyOutbound.sendText.
+    api.on("subagent_ended", async (event, ctx) => {
+        const requesterSessionKey = ctx?.requesterSessionKey;
+        if (!requesterSessionKey)
+            return;
+        markSubagentEnded(requesterSessionKey);
+        console.log(`[XY-SUBAGENT] ended, sessionKey=${event?.targetSessionKey?.slice(0, 30)}, outcome=${event?.outcome}, requester=${requesterSessionKey.slice(0, 30)}`);
+    });
+}
 function registerFullHooks(api) {
+    // SUBAGENT HOOKS: track subagent spawn/end lifecycle for session keep-alive
+    registerSubagentHooks(api);
     // SKILL RETRIEVER HOOK: before_prompt_build hook
     const pluginConfig = api.pluginConfig || {};
     const skillRetrieverConfig = normalizeToolRetrieverConfig({

package/dist/src/bot.js

@@ -16,6 +16,7 @@ import { saveRuntimeInfo } from "./utils/runtime-manager.js";
 import { toolCallNudgeManager } from "./utils/tool-call-nudge-manager.js";
 import { setCsplSteerContext } from "./cspl/steer-context.js";
 import { registerTaskId, decrementTaskIdRef, hasActiveTask, } from "./task-manager.js";
+import { registerSessionKeyMapping, getWaitState, markParentSettled, } from "./subagent-wait-state.js";
 import { logger } from "./utils/logger.js";
 /**
  * Handle an incoming A2A message.
@@ -177,6 +178,11 @@ export async function handleXYMessage(params) {
             },
         });
         log.log(`[BOT] Resolved route, sessionKey=${route.sessionKey}`);
+        // Register sessionKey→A2A sessionId mapping for subagent hook translation.
+        // Hooks receive openclaw sessionKey (e.g. "agent:main:direct:xxx") but
+        // xy_channel operates on A2A sessionId. This bridge lets subagent_spawned/
+        // subagent_ended hooks find the correct wait state.
+        registerSessionKeyMapping(route.sessionKey, parsed.sessionId, parsed.taskId, parsed.messageId);
         // Check for ACP runtime binding on this A2A conversation
         const runtimeRoute = resolveRuntimeConversationBindingRoute({
             route,
@@ -369,6 +375,12 @@ export async function handleXYMessage(params) {
         const cleanup = () => {
             if (cleaned)
                 return;
+            const pendingWait = getWaitState(parsed.sessionId, parsed.taskId);
+            if (pendingWait && pendingWait.deliveredCompletions < pendingWait.expectedCompletions) {
+                // Subagent wait active — skip cleanup, session stays alive
+                log.log(`[BOT] Cleanup suppressed — subagent wait active ${pendingWait.deliveredCompletions}/${pendingWait.expectedCompletions}`);
+                return;
+            }
             cleaned = true;
             log.log(`[BOT] Cleanup started`);
             streamingSignals.delete(parsed.sessionId);
@@ -408,13 +420,35 @@ export async function handleXYMessage(params) {
         log.log(`[BOT-DISPATCH] withReplyDispatcher starting, sessionKey=${route.sessionKey}`);
         await core.channel.reply.withReplyDispatcher({
             dispatcher,
-            onSettled: () => {
+            onSettled: async () => {
                 log.log(`[BOT] onSettled, steered=${steerState.steered}`);
                 // 🔑 When steered, skip cleanup — the first message's dispatcher is still running
                 if (steerState.steered) {
                     log.log(`[BOT] Steered dispatch settled, skipping cleanup`);
                     return;
                 }
+                // Subagent wait state: if parent has pending subagents, mark settled
+                // and defer finalization. Cleanup is suppressed so the session stays alive.
+                const pendingWait = getWaitState(parsed.sessionId, parsed.taskId);
+                if (pendingWait && !pendingWait.parentSettled) {
+                    const transition = markParentSettled(parsed.sessionId, parsed.taskId);
+                    if (transition?.shouldFinalize) {
+                        // All completions arrived before parent settled → finalize now
+                        const { deliverSubagentFinalResult } = await import("./outbound.js");
+                        await deliverSubagentFinalResult({
+                            config,
+                            state: transition.state,
+                            reason: "all-subagent-results-delivered-before-parent-settled",
+                        });
+                        streamingSignals.delete(parsed.sessionId);
+                        log.log(`[BOT] Subagent wait complete on parent settled; final response delivered`);
+                    }
+                    else {
+                        log.log(`[BOT] Subagent wait active, preserving session context for completion`);
+                    }
+                    dispatcherUpdaters.delete(parsed.sessionId);
+                    return;
+                }
                 // cleanup 已由 onIdleComplete 在 onIdle 的 finally 中执行。
                 // onSettled 不做任何清理（直接在这里清理会发生 race condition）。
                 dispatcherUpdaters.delete(parsed.sessionId);

package/dist/src/formatter.d.ts

@@ -10,6 +10,9 @@ export interface SendA2AResponseParams {
     text?: string;
     append: boolean;
     final: boolean;
+    /** Optional: reuse an existing artifactId instead of generating a new one.
+     *  Used by subagent completion to link results to the original artifact. */
+    artifactId?: string;
     files?: Array<{
         fileName: string;
         fileType: string;
@@ -50,6 +53,8 @@ export interface SendStatusUpdateParams {
     messageId: string;
     text: string;
     state: "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "unknown";
+    /** When false, use the exact taskId/messageId passed in. Default true (dynamic lookup). */
+    useLatestTask?: boolean;
 }
 /**
  * Send an A2A task status update.

package/dist/src/formatter.js

@@ -45,7 +45,7 @@ function buildTextPreview(text) {
  * Send an A2A artifact update response.
  */
 export async function sendA2AResponse(params) {
-    const { config, sessionId, taskId, messageId, text, append, final, files, errorCode, errorMessage, log: shouldLog = true } = params;
+    const { config, sessionId, taskId, messageId, text, append, final, artifactId, files, errorCode, errorMessage, log: shouldLog = true } = params;
     const log = logger.withContext(sessionId, taskId);
     // 审批桥接：将 OpenClaw 的审批提示翻译成用户友好的确认文案
     const bridgedText = text === undefined ? text : rewriteOutboundApprovalText(sessionId, text);
@@ -57,7 +57,7 @@ export async function sendA2AResponse(params) {
         lastChunk: true,
         final,
         artifact: {
-            artifactId: uuidv4(),
+            artifactId: artifactId ?? uuidv4(),
             parts: [],
         },
     };
@@ -157,7 +157,7 @@ export async function sendReasoningTextUpdate(params) {
  * Follows A2A protocol standard format with nested status object.
  */
 export async function sendStatusUpdate(params) {
-    const { config, sessionId, taskId, messageId, text, state } = params;
+    const { config, sessionId, taskId, messageId, text, state, useLatestTask = true } = params;
     const log = logger.withContext(sessionId, taskId);
     // 审批桥接和脱敏
     const bridgedText = rewriteOutboundApprovalText(sessionId, text);

package/dist/src/outbound.d.ts

@@ -1,4 +1,11 @@
 type ChannelOutboundAdapter = any;
+import { resolveXYConfig } from "./config.js";
+export declare function deliverSubagentFinalResult(params: {
+    config: ReturnType<typeof resolveXYConfig>;
+    state: import("./subagent-wait-state.js").SubagentWaitState;
+    reason?: string;
+    text?: string;
+}): Promise<void>;
 /**
  * Outbound adapter for sending messages from OpenClaw to XY.
  * Uses Push service for direct message delivery.

package/dist/src/outbound.js

@@ -6,11 +6,45 @@ import { resolveXYConfig } from "./config.js";
 import { XYFileUploadService } from "./file-upload.js";
 import { XYPushService } from "./push.js";
 import { getCurrentSessionContext } from "./tools/session-manager.js";
+import { getWaitState, markCompletionDelivered, clearWaitState, } from "./subagent-wait-state.js";
+import { decrementTaskIdRef } from "./task-manager.js";
+import { sendA2AResponse, sendStatusUpdate } from "./formatter.js";
 import { savePushData } from "./utils/pushdata-manager.js";
 import { getAllPushIds } from "./utils/pushid-manager.js";
 import { logger } from "./utils/logger.js";
 // Special marker for default push delivery when no target is specified
 const DEFAULT_PUSH_MARKER = "default";
+// ─── Subagent completion delivery ──────────────────────────────
+export async function deliverSubagentFinalResult(params) {
+    const { config, state, reason, text } = params;
+    const log = logger.withContext(state.sessionId, state.taskId);
+    const finalText = state.completionTexts.length > 0
+        ? state.completionTexts.join("\n\n")
+        : (text ?? "");
+    await sendStatusUpdate({
+        config,
+        sessionId: state.sessionId,
+        taskId: state.taskId,
+        messageId: state.messageId,
+        text: "任务处理已完成~",
+        state: "completed",
+        useLatestTask: false,
+    });
+    await sendA2AResponse({
+        config,
+        sessionId: state.sessionId,
+        taskId: state.taskId,
+        messageId: state.messageId,
+        text: finalText,
+        append: false,
+        final: true,
+        artifactId: state.artifactId,
+    });
+    clearWaitState(state.sessionId, reason ?? "all-subagent-results-delivered", state.taskId);
+    decrementTaskIdRef(state.sessionId, state.taskId);
+    log.log(`[xyOutbound] Subagent final delivered to original A2A task, reason=${reason}`);
+}
+// ─── MIME types ─────────────────────────────────────────────────
 // File extension to MIME type mapping
 const FILE_TYPE_TO_MIME_TYPE = {
     txt: "text/plain",
@@ -72,20 +106,28 @@ export const xyOutbound = {
         // If the target doesn't contain "::", try to enhance it with taskId from session context
         if (!trimmedTo.includes("::")) {
             logger.log(`[xyOutbound.resolveTarget] Target "${trimmedTo}" missing taskId, looking up session context`);
-            // Try to get the current session context
+            // Try ALS context first (normal agent turn)
             const sessionContext = getCurrentSessionContext();
             if (sessionContext && sessionContext.sessionId === trimmedTo) {
                 const enhancedTarget = `${trimmedTo}::${sessionContext.taskId}`;
-                logger.log(`[xyOutbound.resolveTarget] Enhanced target: ${enhancedTarget}`);
+                logger.log(`[xyOutbound.resolveTarget] Enhanced target from ALS: ${enhancedTarget}`);
                 return {
                     ok: true,
                     to: enhancedTarget,
                 };
             }
-            else {
-                logger.log(`[xyOutbound.resolveTarget] Could not find matching session context for "${trimmedTo}"`);
-                // Still return the original target, but it may fail in sendMedia
+            // Fallback: subagent wait state (ALS is null for subagent completion deliveries)
+            const waitState = getWaitState(trimmedTo);
+            if (waitState) {
+                const enhancedTarget = `${waitState.sessionId}::${waitState.taskId}`;
+                logger.withContext(waitState.sessionId, waitState.taskId).log(`[xyOutbound.resolveTarget] Enhanced target from subagent wait state: ${enhancedTarget}`);
+                return {
+                    ok: true,
+                    to: enhancedTarget,
+                };
             }
+            logger.log(`[xyOutbound.resolveTarget] Could not find matching session context or wait state for "${trimmedTo}"`);
+            // Still return the original target, but it may fail in sendMedia
         }
         // Otherwise, use the provided target (either already in correct format or for sendText)
         logger.log(`[xyOutbound.resolveTarget] Using provided target:`, trimmedTo);
@@ -97,6 +139,52 @@ export const xyOutbound = {
     sendText: async ({ cfg, to, text, accountId }) => {
         // Resolve configuration
         const config = resolveXYConfig(cfg);
+        // ── Subagent completion interception ─────────────────────────
+        // Isolation guards:
+        //   1. ALS context is null (subagent completions arrive outside any agent turn)
+        //   2. A wait state exists for the target sessionId
+        //   3. The taskId matches (enhanced by resolveTarget from wait state)
+        const alsCtx = getCurrentSessionContext();
+        if (!alsCtx && to && to !== DEFAULT_PUSH_MARKER) {
+            const [targetSessionId, targetTaskId] = String(to).split("::");
+            const waitState = getWaitState(targetSessionId, targetTaskId);
+            if (waitState && !waitState.finalizationClaimed) {
+                const delivered = markCompletionDelivered(targetSessionId, targetTaskId, text);
+                if (delivered) {
+                    const { state, isComplete, shouldFinalize } = delivered;
+                    const log = logger.withContext(state.sessionId, state.taskId);
+                    if (shouldFinalize) {
+                        // All completions arrived and parent already settled → send final
+                        log.log(`[xyOutbound.sendText] All subagent results arrived after parent settled, finalizing`);
+                        await deliverSubagentFinalResult({ config, state, reason: "all-subagent-results-delivered-after-parent-settled", text: text });
+                    }
+                    else if (isComplete) {
+                        // All completions arrived but parent hasn't settled yet → defer
+                        log.log(`[xyOutbound.sendText] All subagent results arrived before parent settled, deferring finalization`);
+                    }
+                    else {
+                        // Still waiting for more completions → send progress update
+                        log.log(`[xyOutbound.sendText] Subagent completion ${state.deliveredCompletions}/${state.expectedCompletions}`);
+                        try {
+                            await sendStatusUpdate({
+                                config,
+                                sessionId: state.sessionId,
+                                taskId: state.taskId,
+                                messageId: state.messageId,
+                                text: `已收到子任务结果 ${state.deliveredCompletions}/${state.expectedCompletions}，继续等待其他子任务~`,
+                                state: "working",
+                                useLatestTask: false,
+                            });
+                        }
+                        catch (err) {
+                            log.error(`[xyOutbound.sendText] Failed to send subagent progress status:`, err);
+                        }
+                    }
+                }
+                // Continue with push delivery (subagent result also delivered as push)
+            }
+        }
+        // ── End subagent interception ───────────────────────────────
         // Handle default push marker (for cron jobs without explicit target)
         let actualTo = to;
         if (to === DEFAULT_PUSH_MARKER) {

package/dist/src/reply-dispatcher.js

@@ -2,6 +2,7 @@ import { getXYRuntime } from "./runtime.js";
 import { sendA2AResponse, sendStatusUpdate, sendReasoningTextUpdate, sendCommand } from "./formatter.js";
 import { resolveXYConfig } from "./config.js";
 import { clearRunCrossTaskSentFiles, getCurrentSessionContext } from "./tools/session-manager.js";
+import { getWaitState, clearWaitState, attachHeartbeat, } from "./subagent-wait-state.js";
 import fs from "fs/promises";
 import path from "path";
 import { logger } from "./utils/logger.js";
@@ -187,8 +188,6 @@ export function createXYReplyDispatcher(params) {
                     scopedLog().log(`[DELIVER SKIP] Already sent via onPartialReply`);
                     return;
                 }
-                // DEBUG: 记录 deliver 发送内容
-                scopedLog().log(`[DEBUG-DEDUP] deliver: text_len=${text.length}, accumulated_len=${accumulatedText.length}, text_preview="${text.slice(0, 100)}", accumulated_preview="${accumulatedText.slice(0, 100)}"`);
                 accumulatedText += text;
                 hasSentResponse = true;
                 // 🔑 使用动态taskId发送A2A响应（流式append）
@@ -234,6 +233,34 @@ export function createXYReplyDispatcher(params) {
                 stopStatusInterval();
                 return;
             }
+            // ── Subagent wait state check ─────────────────────────────
+            // If this session has pending subagent completions, suppress final:true
+            // and keep the A2A session alive. The final response will be sent when
+            // all completions arrive via xyOutbound.sendText interception.
+            const waitState = getWaitState(sessionId, taskId);
+            if (waitState &&
+                waitState.deliveredCompletions < waitState.expectedCompletions &&
+                !finalSent) {
+                scopedLog().log(`[ON-IDLE] Waiting for subagent completions ${waitState.deliveredCompletions}/${waitState.expectedCompletions}, suppressing final:true`);
+                try {
+                    await sendStatusUpdate({
+                        config,
+                        sessionId,
+                        taskId,
+                        messageId,
+                        text: "子任务正在处理中，请稍候~",
+                        state: "working",
+                        useLatestTask: false,
+                    });
+                }
+                catch (err) {
+                    scopedLog().error(`[ON-IDLE] Failed to send subagent waiting status:`, err);
+                }
+                // Attach heartbeat so the status interval stays alive during wait
+                attachHeartbeat(sessionId, taskId, stopStatusInterval);
+                return;
+            }
+            // ── End subagent wait state check ─────────────────────────
             // 🔑 用 try/finally 确保 cleanup 在 onIdle 的 async 工作全部完成后才执行。
             // openclaw 的 waitForIdle() 以 void options.onIdle?.() 调用 onIdle，
             // 不会 await 返回的 Promise，因此 onSettled 可能在 onIdle 中途触发。
@@ -280,6 +307,9 @@ export function createXYReplyDispatcher(params) {
                             final: true,
                         });
                         finalSent = true;
+                        if (waitState) {
+                            clearWaitState(sessionId, "main-final-delivered", taskId);
+                        }
                         scopedLog().log(`[ON-IDLE] Sent final response (empty, stream end)`);
                     }
                     catch (err) {
@@ -430,8 +460,11 @@ export function createXYReplyDispatcher(params) {
                         if (dedupApplied) {
                             sendText = text.slice(accumulatedText.length);
                         }
-                        // DEBUG: 记录 onPartialReply 去重详情
-                        scopedLog().log(`[DEBUG-DEDUP] onPartialReply: text_len=${text.length}, accumulated_len=${accumulatedText.length}, sendText_len=${sendText.length}, dedup=${dedupApplied}, text_preview="${text.slice(0, 100)}", accumulated_preview="${accumulatedText.slice(0, 100)}", sendText_preview="${sendText.slice(0, 100)}"`);
+                        else {
+                            // 新文本不以已累积内容为前缀（如工具调用后模型重新开始生成），
+                            // 更新 accumulatedText 为当前文本，后续基于此新前缀做去重
+                            accumulatedText = "";
+                        }
                         accumulatedText += sendText;
                         hasSentResponse = true;
                         if (sendText.length > 0) {
@@ -443,7 +476,7 @@ export function createXYReplyDispatcher(params) {
                                 text: sendText,
                                 append: true,
                                 final: false,
-                                log: true,
+                                log: false,
                             });
                         }
                     }

package/dist/src/subagent-wait-state.d.ts

@@ -0,0 +1,61 @@
+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;
+    stopHeartbeat?: () => void;
+}
+export interface SubagentWaitTransition {
+    state: SubagentWaitState;
+    isComplete: boolean;
+    shouldFinalize: boolean;
+}
+/**
+ * Register a mapping from openclaw sessionKey to A2A sessionId/taskId.
+ * Called in bot.ts when a new message dispatch begins.
+ */
+export declare function registerSessionKeyMapping(sessionKey: string, sessionId: string, taskId: string, messageId: string): void;
+/**
+ * Look up the A2A sessionId for a given openclaw sessionKey.
+ * Used in hooks (index.ts) to translate requesterSessionKey to A2A sessionId.
+ */
+export declare function resolveSessionIdFromSessionKey(sessionKey: string): {
+    sessionId: string;
+    taskId: string;
+    messageId: string;
+} | null;
+/**
+ * Remove a sessionKey→sessionId mapping (cleanup when wait state resolved).
+ */
+export declare function unregisterSessionKeyMapping(sessionKey: string): void;
+/**
+ * Called from subagent_spawned hook. Increments expected completion count.
+ * If no wait state exists yet, creates one (sessions_spawn may happen before sessions_yield).
+ */
+export declare function markSubagentSpawned(sessionKey: string): number;
+/**
+ * Called from subagent_ended hook. Marks a subagent run as ended.
+ * Does NOT decrement expected count — that's done when completion is delivered via outbound.
+ */
+export declare function markSubagentEnded(sessionKey: string): void;
+/**
+ * Called from xyOutbound.sendText when a subagent completion is delivered.
+ * Increments delivered count and returns transition state.
+ */
+export declare function markCompletionDelivered(sessionId: string, taskId: string, text?: string): SubagentWaitTransition | null;
+/**
+ * Called from bot.ts onSettled. Marks parent dispatcher as settled.
+ * Returns transition with shouldFinalize if all completions already arrived.
+ */
+export declare function markParentSettled(sessionId: string, taskId: string): SubagentWaitTransition | null;
+export declare function attachHeartbeat(sessionId: string, taskId: string, stopHeartbeat: () => void): 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;

package/dist/src/subagent-wait-state.js

@@ -0,0 +1,223 @@
+// Subagent wait state manager.
+//
+// Tracks sessions that are waiting for subagent completions after sessions_yield.
+// Subagent spawn/end is detected via subagent_spawned / subagent_ended hooks (index.ts).
+// Completion delivery is intercepted in xyOutbound.sendText (outbound.ts).
+//
+// Isolation: xyOutbound.sendText also serves cron pushes and normal message-tool calls.
+// Guards ensure these paths never collide with subagent result interception:
+//   1. ALS context guard — subagent completions arrive with ALS null
+//   2. Wait state match — only sessions that have yielded have a wait state
+//   3. TaskId match — subagent delivery's "to" is a bare sessionId, enhanced via wait state
+//
+// TTL: wait states expire after WAIT_TTL_MS (30 min) to avoid stale leaks.
+// Only one finalization path wins via finalizationClaimed flag.
+import { randomUUID } from "crypto";
+import { logger } from "./utils/logger.js";
+// ─── Global state ──────────────────────────────────────────────
+const WAIT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const _g = globalThis;
+if (!_g.__xySubagentWaitStates) {
+    _g.__xySubagentWaitStates = new Map();
+}
+if (!_g.__xySessionKeyToSessionId) {
+    _g.__xySessionKeyToSessionId = new Map();
+}
+const waitStates = _g.__xySubagentWaitStates;
+const sessionKeyMap = _g.__xySessionKeyToSessionId;
+// ─── Helpers ───────────────────────────────────────────────────
+function waitKey(sessionId, taskId) {
+    return `${sessionId}::${taskId}`;
+}
+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;
+}
+// ─── SessionKey ↔ SessionId mapping ────────────────────────────
+/**
+ * Register a mapping from openclaw sessionKey to A2A sessionId/taskId.
+ * Called in bot.ts when a new message dispatch begins.
+ */
+export function registerSessionKeyMapping(sessionKey, sessionId, taskId, messageId) {
+    if (!sessionKey || !sessionId)
+        return;
+    sessionKeyMap.set(sessionKey, { sessionId, taskId, messageId });
+}
+/**
+ * Look up the A2A sessionId for a given openclaw sessionKey.
+ * Used in hooks (index.ts) to translate requesterSessionKey to A2A sessionId.
+ */
+export function resolveSessionIdFromSessionKey(sessionKey) {
+    return sessionKeyMap.get(sessionKey) ?? null;
+}
+/**
+ * Remove a sessionKey→sessionId mapping (cleanup when wait state resolved).
+ */
+export function unregisterSessionKeyMapping(sessionKey) {
+    sessionKeyMap.delete(sessionKey);
+}
+// ─── Wait state management ─────────────────────────────────────
+function getStatesArray(sessionId) {
+    const raw = waitStates.get(sessionId);
+    if (!raw)
+        return [];
+    const active = raw.filter((s) => {
+        if (!isExpired(s))
+            return true;
+        s.stopHeartbeat?.();
+        logger.withContext(sessionId, s.taskId).log(`[SUBAGENT-WAIT] Expired wait state cleared, expected=${s.expectedCompletions}, delivered=${s.deliveredCompletions}`);
+        return false;
+    });
+    if (active.length > 0) {
+        waitStates.set(sessionId, active);
+    }
+    else {
+        waitStates.delete(sessionId);
+    }
+    return active;
+}
+/**
+ * Called from subagent_spawned hook. Increments expected completion count.
+ * If no wait state exists yet, creates one (sessions_spawn may happen before sessions_yield).
+ */
+export function markSubagentSpawned(sessionKey) {
+    const mapped = resolveSessionIdFromSessionKey(sessionKey);
+    if (!mapped) {
+        logger.log(`[SUBAGENT-WAIT] No session mapping for sessionKey=${sessionKey.slice(0, 30)}`);
+        return 0;
+    }
+    const { sessionId, taskId, messageId } = mapped;
+    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);
+    waitStates.set(sessionId, states);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Subagent spawned, expected=${state.expectedCompletions}`);
+    return state.expectedCompletions;
+}
+/**
+ * Called from subagent_ended hook. Marks a subagent run as ended.
+ * Does NOT decrement expected count — that's done when completion is delivered via outbound.
+ */
+export function markSubagentEnded(sessionKey) {
+    const mapped = resolveSessionIdFromSessionKey(sessionKey);
+    if (!mapped)
+        return;
+    const { sessionId, taskId } = mapped;
+    const states = getStatesArray(sessionId);
+    const state = states.find((s) => s.taskId === taskId);
+    if (!state)
+        return;
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Subagent ended, delivered=${state.deliveredCompletions}/${state.expectedCompletions}`);
+}
+/**
+ * Called from xyOutbound.sendText when a subagent completion is delivered.
+ * Increments delivered count and returns transition state.
+ */
+export function markCompletionDelivered(sessionId, taskId, text) {
+    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 completion delivery`);
+        return null;
+    }
+    state.deliveredCompletions += 1;
+    if (text?.trim()) {
+        state.completionTexts.push(text.trim());
+    }
+    const complete = isComplete(state);
+    const shouldFinalize = claimFinalizationIfReady(state);
+    waitStates.set(sessionId, states);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Completion delivered=${state.deliveredCompletions}/${state.expectedCompletions}, complete=${complete}, shouldFinalize=${shouldFinalize}`);
+    return { state, isComplete: complete, shouldFinalize };
+}
+/**
+ * Called from bot.ts onSettled. Marks parent dispatcher as settled.
+ * Returns transition with shouldFinalize if all completions already arrived.
+ */
+export function markParentSettled(sessionId, taskId) {
+    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);
+    waitStates.set(sessionId, states);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Parent settled, completions=${state.deliveredCompletions}/${state.expectedCompletions}, shouldFinalize=${shouldFinalize}`);
+    return { state, isComplete: complete, shouldFinalize };
+}
+export function attachHeartbeat(sessionId, taskId, stopHeartbeat) {
+    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 heartbeat attachment`);
+        return;
+    }
+    state.stopHeartbeat = stopHeartbeat;
+    waitStates.set(sessionId, states);
+    logger.withContext(sessionId, taskId).log(`[SUBAGENT-WAIT] Heartbeat attached`);
+}
+// ─── Query functions ───────────────────────────────────────────
+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: return oldest wait state when taskId not specified
+    return states[0] ?? null;
+}
+export function hasWaitState(sessionId, taskId) {
+    return getWaitState(sessionId, taskId) !== null;
+}
+export function clearWaitState(sessionId, reason, taskId) {
+    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);
+    state.stopHeartbeat?.();
+    if (states.length > 0) {
+        waitStates.set(sessionId, states);
+    }
+    else {
+        waitStates.delete(sessionId);
+    }
+    logger.withContext(sessionId, state.taskId).log(`[SUBAGENT-WAIT] Cleared wait state, reason=${reason}, remaining=${states.length}`);
+    return state;
+}

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

@@ -1,8 +1,14 @@
+interface TaskIdEntry {
+    taskId: string;
+    messageId: string;
+    updatedAt: number;
+}
 interface TaskIdBinding {
     sessionId: string;
     currentTaskId: string;
     currentMessageId: string;
     updatedAt: number;
+    tasks?: TaskIdEntry[];
 }
 /**
  * 注册或更新session的活跃taskId。
@@ -11,8 +17,10 @@ interface TaskIdBinding {
 export declare function registerTaskId(sessionId: string, taskId: string, messageId: string): boolean;
 /**
  * 移除session的活跃taskId（消息处理完成时调用）。
+ * @param expectedTaskId 可选：精确移除指定的 taskId，而非整个 session 绑定。
+ *   用于 subagent completion 等需要精确清理特定 task 的场景。
  */
-export declare function decrementTaskIdRef(sessionId: string): void;
+export declare function decrementTaskIdRef(sessionId: string, expectedTaskId?: string): void;
 /**
  * 获取session的当前活跃taskId。
  * 仅供 reply-dispatcher 跨链读取 steer 更新后的 taskId。

package/dist/src/task-manager.js

@@ -12,6 +12,27 @@ if (!_g.__xyActiveTaskIds) {
     _g.__xyActiveTaskIds = new Map();
 }
 const activeTaskIds = _g.__xyActiveTaskIds;
+function normalizeTasks(binding) {
+    if (Array.isArray(binding.tasks) && binding.tasks.length > 0) {
+        return binding.tasks;
+    }
+    return [{
+            taskId: binding.currentTaskId,
+            messageId: binding.currentMessageId,
+            updatedAt: binding.updatedAt,
+        }];
+}
+function syncCurrent(binding, tasks) {
+    binding.tasks = tasks;
+    const current = tasks[tasks.length - 1];
+    if (!current) {
+        activeTaskIds.delete(binding.sessionId);
+        return;
+    }
+    binding.currentTaskId = current.taskId;
+    binding.currentMessageId = current.messageId;
+    binding.updatedAt = current.updatedAt;
+}
 /**
  * 注册或更新session的活跃taskId。
  * Returns true if this was an update (session already had an active task).
@@ -20,9 +41,9 @@ export function registerTaskId(sessionId, taskId, messageId) {
     const existing = activeTaskIds.get(sessionId);
     if (existing) {
         logger.log(`[TASK_MANAGER] Updating taskId: ${existing.currentTaskId} → ${taskId}`);
-        existing.currentTaskId = taskId;
-        existing.currentMessageId = messageId;
-        existing.updatedAt = Date.now();
+        const tasks = normalizeTasks(existing).filter((entry) => entry.taskId !== taskId);
+        tasks.push({ taskId, messageId, updatedAt: Date.now() });
+        syncCurrent(existing, tasks);
         return true; // isUpdate
     }
     else {
@@ -31,6 +52,7 @@ export function registerTaskId(sessionId, taskId, messageId) {
             currentTaskId: taskId,
             currentMessageId: messageId,
             updatedAt: Date.now(),
+            tasks: [{ taskId, messageId, updatedAt: Date.now() }],
         });
         logger.log(`[TASK_MANAGER] Registered new taskId: ${taskId}`);
         return false;
@@ -38,10 +60,31 @@ export function registerTaskId(sessionId, taskId, messageId) {
 }
 /**
  * 移除session的活跃taskId（消息处理完成时调用）。
+ * @param expectedTaskId 可选：精确移除指定的 taskId，而非整个 session 绑定。
+ *   用于 subagent completion 等需要精确清理特定 task 的场景。
  */
-export function decrementTaskIdRef(sessionId) {
-    logger.log(`[TASK_MANAGER] Removing taskId`);
-    activeTaskIds.delete(sessionId);
+export function decrementTaskIdRef(sessionId, expectedTaskId) {
+    if (!expectedTaskId) {
+        logger.log(`[TASK_MANAGER] Removing taskId`);
+        activeTaskIds.delete(sessionId);
+        return;
+    }
+    const existing = activeTaskIds.get(sessionId);
+    if (!existing)
+        return;
+    const tasks = normalizeTasks(existing);
+    const nextTasks = tasks.filter((entry) => entry.taskId !== expectedTaskId);
+    if (nextTasks.length === tasks.length) {
+        logger.log(`[TASK_MANAGER] Preserving taskId ${existing.currentTaskId}; completed task ${expectedTaskId} is not active`);
+        return;
+    }
+    syncCurrent(existing, nextTasks);
+    if (nextTasks.length > 0) {
+        logger.log(`[TASK_MANAGER] Removed taskId ${expectedTaskId}, restored current taskId ${existing.currentTaskId}`);
+    }
+    else {
+        logger.log(`[TASK_MANAGER] Removing taskId (last task ${expectedTaskId})`);
+    }
 }
 /**
  * 获取session的当前活跃taskId。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ynhcj/xiaoyi-channel",
-  "version": "0.0.187-next",
+  "version": "0.0.188-next",
   "description": "OpenClaw Xiaoyi Channel plugin - Xiaoyi A2A protocol integration",
   "type": "module",
   "main": "./dist/index.js",