@ynhcj/xiaoyi-channel 0.0.1-release2026060601 → 0.0.1-task

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
@@ -44,23 +45,37 @@ function extractSkillNameFromPath(filePath) {
  * the `after_tool_call` hook and write the skill name to the skills log.
  */
 function registerSkillsDiagnosticHook(api) {
-    // Tool name → skill name mapping for direct tool-based skill usage logging
-    const TOOL_SKILL_MAP = {
-        get_user_location: "GetCurrentLocation",
-        get_calendar_tool_schema: "Schedule",
-        get_note_tool_schema: "memorandum",
-        get_photo_tool_schema: "gallery",
-        get_contact_tool_schema: "contact",
-        get_device_file_tool_schema: "file",
-        get_alarm_tool_schema: "clock",
-        message: "message",
-        get_phone_tool_schema: "phone",
-        get_collection_tool_schema: "xiaoyi-collection",
-        image_reading: "xiaoyi-image-understanding"
+    // Skill name → tool names mapping for direct tool-based skill usage logging
+    const SKILL_TOOLS = {
+        GetCurrentLocation: ["get_user_location"],
+        Schedule: ["create_calendar_event", "search_calendar_event"],
+        memorandum: ["create_note", "search_notes", "modify_note"],
+        gallery: ["search_photo_gallery", "save_media_to_gallery"],
+        contact: ["search_contact"],
+        file: ["search_file", "upload_file", "save_file_to_file_manager"],
+        clock: ["create_alarm", "delete_alarm", "search_alarm", "modify_alarm"],
+        message: ["search_message", "send_message"],
+        phone: ["call_phone"],
+        "xiaoyi-collection": ["add_collection", "query_collection", "delete_collection"],
+        "xiaoyi-image-understanding": ["image_reading"],
     };
+    // Inverted to tool name → skill name for lookup
+    const TOOL_SKILL_MAP = Object.fromEntries(Object.entries(SKILL_TOOLS).flatMap(([skill, tools]) => tools.map((t) => [t, skill])));
+    // Resolve the actual tool name from call_device_tool wrapper.
+    // The model calls call_device_tool({ toolName: "...", arguments: {...} })
+    // — the real tool name is inside params, not event.toolName.
+    function resolveActualToolName(event) {
+        if (event.toolName === "call_device_tool") {
+            const inner = event.params?.toolName;
+            if (typeof inner === "string" && inner.length > 0)
+                return inner;
+        }
+        return event.toolName;
+    }
     // Log skill usage for known device tools on before_tool_call
     api.on("before_tool_call", async (event, _ctx) => {
-        const skillName = TOOL_SKILL_MAP[event.toolName];
+        const actualToolName = resolveActualToolName(event);
+        const skillName = TOOL_SKILL_MAP[actualToolName];
         if (skillName) {
             writeSkillUsage(skillName);
         }
@@ -75,19 +90,32 @@ function registerSkillsDiagnosticHook(api) {
         }
     });
 }
+/**
+ * 从 openclaw sessionKey 解析 cron jobId。
+ * 格式形如 `agent:<agentId>:cron:<jobId>:run:<startedAtTs>`（隔离 run 为
+ * `cron:<jobId>`），jobId 位于 "cron:" 之后到下一个冒号/空白之前。
+ */
+function parseCronJobIdFromSessionKey(sessionKey) {
+    const match = sessionKey.match(/cron:([^:\s]+)/);
+    return match ? match[1] : undefined;
+}
 /**
  * Register the cron detection hook.
  *
  * When openclaw's cron runner triggers a tool call, the sessionKey has the
- * format "cron:<jobId>".  We use this to mark the toolCallId in a global Map
+ * format "cron:<jobId>"（或 agent 展开后的 `agent:<id>:cron:<jobId>:run:<ts>`）。
+ * We use this to mark the toolCallId in a global Map
  * so that sendCommand() can route the command through the push channel
  * instead of the (non-existent) WebSocket session.
  */
 function registerCronDetectionHook(api) {
     api.on("before_tool_call", async (event, ctx) => {
-        // sessionKey 前缀依赖 openclaw 版本行为，不一定可靠；
-        // isCronActive() 由 provider.ts 根据消息内容 [cron:...] 设置，更可靠。
-        if ((ctx.sessionKey?.startsWith("cron:") || isCronActive()) && event.toolCallId) {
+        // sessionKey 前缀依赖 openclaw 版本行为，不一定可靠；isCronActive(jobId)
+        // 按 jobId 精确判断（provider 已从消息 [cron:...] 标记过该 job），替代
+        // 原先的全局 120s 时间戳，避免把普通对话/其它 job 的工具调用误判为 cron。
+        const sessionKey = ctx.sessionKey ?? "";
+        const sessionJobId = parseCronJobIdFromSessionKey(sessionKey);
+        if ((sessionKey.includes("cron:") || isCronActive(sessionJobId)) && event.toolCallId) {
             markCronToolCall(event.toolCallId);
             // 存储 runId，供 call_device_tool 在 ALS 缺失时构造合成 SessionContext
             if (event.runId) {
@@ -305,6 +333,53 @@ function registerCronRecoveryHook(api) {
         logger.log(`${logTag} ═══════════════════════════════════════════`);
     });
 }
+/**
+ * 从 sessions_spawn 工具结果中提取 ACP child sessionKey。
+ * 兼容三种 result 形态：{status, childSessionKey} 直返、JSON 字符串、
+ * {content:[{text: "<json>"}], details:{...}} 工具信封。
+ * 仅接受 status="accepted" 且 key 形如 agent:<id>:acp:<uuid> 的结果。
+ */
+function extractAcceptedAcpChildSessionKey(result) {
+    const pick = (obj) => {
+        if (!obj || typeof obj !== "object")
+            return null;
+        const record = obj;
+        if (record.status !== "accepted")
+            return null;
+        const key = record.childSessionKey;
+        return typeof key === "string" && key.includes(":acp:") ? key : null;
+    };
+    const direct = pick(result);
+    if (direct)
+        return direct;
+    const envelope = result;
+    const fromDetails = pick(envelope?.details);
+    if (fromDetails)
+        return fromDetails;
+    if (Array.isArray(envelope?.content)) {
+        for (const item of envelope.content) {
+            if (typeof item?.text !== "string")
+                continue;
+            try {
+                const fromText = pick(JSON.parse(item.text));
+                if (fromText)
+                    return fromText;
+            }
+            catch {
+                // 非 JSON 文本，忽略
+            }
+        }
+    }
+    if (typeof result === "string") {
+        try {
+            return pick(JSON.parse(result));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
 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.
@@ -317,6 +392,32 @@ function registerSubagentHooks(api) {
             logger.log(`[XY-SUBAGENT] spawned, requesterSessionKey=${requesterSessionKey.slice(0, 30)}, expected=${count}`);
         }
     });
+    // ACP SPAWN TRACKING: openclaw 的 subagent_spawned hook 仅由内嵌 subagent
+    // 路径（subagent-spawn.ts）发射；acp-spawn.ts（runtime="acp"，如 Claude Code）
+    // 不发射 —— 实测 ACP run 仅在结束时经 run registry 触发 subagent_ended，
+    // 导致等待态从未建立、父 turn onIdle 直接发 final 结束对话。
+    // 因此在 after_tool_call 补记：sessions_spawn 成功且 childSessionKey 为 ACP
+    // 形态时递增等待计数。内嵌 subagent 的 childKey 形如 agent:<id>:subagent:<id>，
+    // 不命中此分支，仍由 subagent_spawned hook 负责，不会重复计数。
+    api.on("after_tool_call", async (event, ctx) => {
+        try {
+            if (event?.toolName !== "sessions_spawn" || event?.error)
+                return;
+            const childKey = extractAcceptedAcpChildSessionKey(event?.result);
+            if (!childKey)
+                return;
+            const sessionKey = ctx?.sessionKey;
+            if (!sessionKey)
+                return;
+            const count = markSubagentSpawned(sessionKey);
+            if (count > 0) {
+                logger.log(`[XY-SUBAGENT] ACP spawned, childSessionKey=${childKey.slice(0, 40)}, expected=${count}`);
+            }
+        }
+        catch (err) {
+            logger.error(`[XY-SUBAGENT] Error tracking ACP spawn:`, err);
+        }
+    });
     // subagent_ended: fires when a subagent run terminates (complete/error/killed).
     // This is the PRIMARY delivery tracking mechanism. When all expected
     // subagents have ended and parent has settled, we finalize the A2A session.
@@ -331,15 +432,13 @@ 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`);
+                // Grace: announce 投递的 sendText 与 subagent_ended hook 并发到达
+                // （实测 sendText 可能先于 hook 约 1s，也可能晚于 hook；长文本还会
+                // 被 textChunkLimit 分片成多次 sendText）。捕获窗口直到
+                // finalDeliveryStarted 才关闭，此处的等待直接扩大迟到来片的入窗机会。
+                await new Promise((r) => setTimeout(r, 3000));
+                // 最终交付由对话管理层统一负责（含 config 解析、final 帧、清理）
                 await deliverSubagentFinalResult({
-                    config: config,
                     state: transition.state,
                     reason: "all-subagents-ended-after-parent-settled",
                 });
@@ -354,14 +453,45 @@ 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 ?? "";
+                // 从 sessionKey（agent:<id>:cron:<jobId>:run:<ts>）解析 jobId，只结束
+                // 该 job 的 turn；isCronActive(jobId) 作为无 cron 前缀版本的兜底（按
+                // jobId 精确判断，普通对话的 lifecycle end 不会命中）。
+                const cronJobId = parseCronJobIdFromSessionKey(sessionKey);
+                if (sessionKey.includes("cron:") || sessionKey.startsWith("cron:") || isCronActive(cronJobId)) {
+                    logger.log(`[XY-CRON] Cron run lifecycle end, sessionKey=${sessionKey || "unknown"}, jobId=${cronJobId ?? "-"}`);
+                    notifyCronAgentEnd(cronJobId);
+                }
+            }
+            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({
         enabled: pluginConfig.skillRetrieverEnabled ?? true,
-        maxTools: pluginConfig.skillRetrieverMaxTools ?? 2,
+        maxTools: pluginConfig.skillRetrieverMaxTools ?? 6,
         includeUninstalledOnly: true,
         envFilePath: "~/.openclaw/.xiaoyienv",
-        timeoutMs: pluginConfig.skillRetrieverTimeoutMs ?? 1000,
+        timeoutMs: pluginConfig.skillRetrieverTimeoutMs ?? 10000,
     });
     const beforePromptBuildHandler = createBeforePromptBuildHandler(skillRetrieverConfig);
     api.on("before_prompt_build", async (event, ctx) => {

package/dist/src/bot.js

@@ -17,7 +17,6 @@ import { toolCallNudgeManager } from "./utils/tool-call-nudge-manager.js";
 import { setCsplSteerContext } from "./cspl/steer-context.js";
 import { resolveActiveEmbeddedRunSessionId, queueAgentHarnessMessage, } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { registerTaskId, decrementTaskIdRef, hasActiveTask, } from "./task-manager.js";
-import { registerSessionKeyMapping, getWaitState, hasWaitState, markParentSettled, cacheXYConfig, } from "./subagent-wait-state.js";
 import { logger } from "./utils/logger.js";
 /**
  * Handle an incoming A2A message.
@@ -166,7 +165,6 @@ export async function handleXYMessage(params) {
         const runCrossTaskContext = extractRunCrossTaskContext(parsed.parts);
         // Resolve configuration (needed for status updates)
         const config = resolveXYConfig(cfg);
-        cacheXYConfig(config);
         // ✅ Resolve agent route (following feishu pattern)
         // accountId is "default" for XY (single account mode)
         // Use sessionId as peer.id to ensure all messages in the same session share context
@@ -180,16 +178,6 @@ 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.
-        // IMPORTANT: Only register on the FIRST message. Steer messages have a
-        // different taskId — overwriting the mapping would break subagent wait
-        // state tracking for the original message's subagents.
-        if (!isUpdate) {
-            registerSessionKeyMapping(route.sessionKey, parsed.sessionId, parsed.taskId, parsed.messageId);
-        }
         // Check for ACP runtime binding on this A2A conversation
         const runtimeRoute = resolveRuntimeConversationBindingRoute({
             route,
@@ -313,7 +301,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}`);
@@ -397,15 +385,6 @@ export async function handleXYMessage(params) {
             cleaned = true;
             log.log(`[BOT] Cleanup started, steered=${steerState.steered}, skipReg=${skipReg}`);
             if (!skipReg) {
-                // Check for pending subagent wait on this session
-                const pendingWait = getWaitState(parsed.sessionId, parsed.taskId) ??
-                    (hasWaitState(parsed.sessionId) ? { deliveredCompletions: 0, expectedCompletions: 1 } : null);
-                if (pendingWait && pendingWait.deliveredCompletions < pendingWait.expectedCompletions) {
-                    // Subagent wait active — skip cleanup, session stays alive
-                    log.log(`[BOT] Cleanup suppressed — subagent wait active on session, taskId=${parsed.taskId}`);
-                    cleaned = false;
-                    return;
-                }
                 decrementTaskIdRef(parsed.sessionId);
             }
             else {
@@ -454,27 +433,6 @@ export async function handleXYMessage(params) {
                     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",
-                        });
-                        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);
@@ -486,7 +444,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";
@@ -23,16 +23,14 @@ import { getAlarmToolSchemaTool } from "./tools/get-alarm-tool-schema.js";
 import { getCollectionToolSchemaTool } from "./tools/get-collection-tool-schema.js";
 import { loginTokenTool } from "./tools/login-token-tool.js";
 import { agentAsSkillTool } from "./tools/agent-as-skill-tool.js";
-import { discoverCrossDevicesTool } from "./tools/discover-cross-devices-tool.js";
-import { sendCrossDeviceTaskTool } from "./tools/send-cross-device-task-tool.js";
+// import { discoverCrossDevicesTool } from "./tools/discover-cross-devices-tool.js";
+// import { sendCrossDeviceTaskTool } from "./tools/send-cross-device-task-tool.js";
 import { displayA2UICardByPathTool } from "./tools/display-a2ui-card-bypath-tool.js";
-import { checkPluginPrivilegeTool } from "./tools/check-plugin-privilege-tool.js";
+// import { checkPluginPrivilegeTool } from "./tools/check-plugin-privilege-tool.js";
 import { invokeTool } from "./tools/invoke.js";
 import { xiaoyiAppendReferenceTool } from "./tools/xiaoyi-append-reference.js";
 const ALL_TOOLS = [
     locationTool,
-    discoverCrossDevicesTool,
-    sendCrossDeviceTaskTool,
     displayA2UICardByPathTool,
     callDeviceTool,
     getNoteToolSchemaTool,
@@ -51,7 +49,6 @@ const ALL_TOOLS = [
     saveSelfEvolutionSkillTool,
     loginTokenTool,
     agentAsSkillTool,
-    checkPluginPrivilegeTool,
     invokeTool,
     xiaoyiAppendReferenceTool,
 ];
@@ -158,7 +155,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/config-schema.d.ts

@@ -49,6 +49,19 @@ export declare const xyConfigSchema: {
             readonly type: "string";
             readonly description: "Default session ID for push notifications (used when no target is specified, e.g., in cron jobs)";
         };
+        readonly terminalFrameDelayMs: {
+            readonly type: "number";
+            readonly description: "Delay in ms before sending terminal frames (completed status + final) so the content artifact clears downstream pipelines first; 0 disables";
+            readonly default: 300;
+        };
+        readonly pinnedSessionIds: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "A2A sessionIds that never change (e.g. [\"00000000\"]). For these, clearContext triggers an explicit openclaw session reset (sessions.reset) to isolate context. Set to [] to disable.";
+            readonly default: readonly ["00000000"];
+        };
     };
     readonly required: readonly ["apiKey", "agentId", "uid", "apiId", "pushId"];
 };

package/dist/src/config-schema.js

@@ -50,6 +50,17 @@ export const xyConfigSchema = {
             type: "string",
             description: "Default session ID for push notifications (used when no target is specified, e.g., in cron jobs)",
         },
+        terminalFrameDelayMs: {
+            type: "number",
+            description: "Delay in ms before sending terminal frames (completed status + final) so the content artifact clears downstream pipelines first; 0 disables",
+            default: 300,
+        },
+        pinnedSessionIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "A2A sessionIds that never change (e.g. [\"00000000\"]). For these, clearContext triggers an explicit openclaw session reset (sessions.reset) to isolate context. Set to [] to disable.",
+            default: ["00000000"],
+        },
     },
     required: ["apiKey", "agentId", "uid", "apiId", "pushId"],
 };

package/dist/src/config.js

@@ -27,6 +27,11 @@ export function resolveXYConfig(cfg) {
         fileUploadUrl: xyConfig.fileUploadUrl ?? "http://localhost:8767",
         pushUrl: xyConfig.pushUrl,
         defaultSessionId: xyConfig.defaultSessionId,
+        terminalFrameDelayMs: xyConfig.terminalFrameDelayMs ?? 300,
+        // 固定会话列表：缺省默认 ["00000000"]；显式配置 [] 表示禁用 reset 特殊处理
+        pinnedSessionIds: Array.isArray(xyConfig.pinnedSessionIds)
+            ? xyConfig.pinnedSessionIds.filter((id) => typeof id === "string" && id.trim() !== "")
+            : ["00000000"],
     };
 }
 /**

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

@@ -0,0 +1,96 @@
+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;
+}>;
+/**
+ * dispatch 时登记在途 turn（bot.ts 创建 dispatcher 后调用）。
+ * 注意：steer 直接注入成功的路径不 dispatch，不得登记。
+ */
+export declare function markTurnInflight(sessionId: string, taskId: string): void;
+/** turn 不再产生流式帧时清除在途标记（onIdle 入口 / onSettled 兜底）。 */
+export declare function clearTurnInflight(sessionId: string, taskId: string): void;
+/**
+ * 绑定 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 发送终态帧并真正
+ * 结束当前 A2A session：
+ *   1. completed 状态帧（"任务处理已完成~"）→ final:true 全文本帧（合并
+ *      completionTexts）——与 reply-dispatcher 正常终态同序，xy_tester
+ *      与客户端依赖该顺序
+ *   2. 清理等待态、停止心跳、移除任务链
+ *   3. 会话状态迁移到 completed
+ */
+export declare function deliverSubagentFinalResult(params: {
+    state: SubagentWaitState;
+    reason?: string;
+    text?: string;
+}): Promise<void>;