@ynhcj/xiaoyi-channel 0.0.231-next → 0.0.232-next

package/dist/index.js

@@ -15,6 +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, 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
@@ -88,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) {
@@ -318,15 +333,165 @@ 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.
+    api.on("subagent_spawned", async (_event, ctx) => {
+        const requesterSessionKey = ctx?.requesterSessionKey;
+        if (!requesterSessionKey)
+            return;
+        const count = markSubagentSpawned(requesterSessionKey);
+        if (count > 0) {
+            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.
+    api.on("subagent_ended", async (event, ctx) => {
+        try {
+            const requesterSessionKey = ctx?.requesterSessionKey;
+            if (!requesterSessionKey) {
+                logger.log(`[XY-SUBAGENT-END] no requesterSessionKey in ctx`);
+                return;
+            }
+            const transition = markSubagentEnded(requesterSessionKey);
+            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...`);
+                // Grace: announce 投递的 sendText 与 subagent_ended hook 并发到达
+                // （实测 sendText 可能先于 hook 约 1s，也可能晚于 hook；长文本还会
+                // 被 textChunkLimit 分片成多次 sendText）。捕获窗口直到
+                // finalDeliveryStarted 才关闭，此处的等待直接扩大迟到来片的入窗机会。
+                await new Promise((r) => setTimeout(r, 3000));
+                // 最终交付由对话管理层统一负责（含 config 解析、final 帧、清理）
+                await deliverSubagentFinalResult({
+                    state: transition.state,
+                    reason: "all-subagents-ended-after-parent-settled",
+                });
+                logger.log(`[XY-SUBAGENT-END] Finalized A2A session after all subagents ended`);
+            }
+        }
+        catch (err) {
+            logger.error(`[XY-SUBAGENT-END] Error in subagent_ended hook:`, err);
+        }
+    });
+}
 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/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,7 +23,10 @@ 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 { displayA2UICardByPathTool } from "./tools/display-a2ui-card-bypath-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 = [
@@ -152,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/conversation/conversation-manager.d.ts

@@ -29,6 +29,13 @@ export declare function listActiveTaskBindings(): Array<{
     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 等待态跟踪稳定）。
@@ -74,9 +81,11 @@ export declare function getWaitState(sessionId: string, taskId?: string): Subage
 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 帧
+ * 当所有 subagent 完成且父 turn 已 settle 时，由 manager 发送终态帧并真正
+ * 结束当前 A2A session：
+ *   1. completed 状态帧（"任务处理已完成~"）→ final:true 全文本帧（合并
+ *      completionTexts）——与 reply-dispatcher 正常终态同序，xy_tester
+ *      与客户端依赖该顺序
  *   2. 清理等待态、停止心跳、移除任务链
  *   3. 会话状态迁移到 completed
  */

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

@@ -43,6 +43,8 @@ export function getSession(sessionId) {
     return sessions.get(sessionId) ?? null;
 }
 export function deleteSession(sessionId) {
+    const session = sessions.get(sessionId);
+    session?.outboundQueue.destroy();
     sessions.delete(sessionId);
 }
 export function listSessions() {
@@ -136,6 +138,28 @@ export function listActiveTaskBindings() {
     }
     return result;
 }
+// ─── 在途 turn 跟踪（subagent 终态帧时机门控） ───────────────
+/**
+ * dispatch 时登记在途 turn（bot.ts 创建 dispatcher 后调用）。
+ * 注意：steer 直接注入成功的路径不 dispatch，不得登记。
+ */
+export function markTurnInflight(sessionId, taskId) {
+    const session = getOrCreateSession(sessionId);
+    if (!session.inflightTurns) {
+        session.inflightTurns = new Set();
+    }
+    session.inflightTurns.add(taskId);
+}
+/** turn 不再产生流式帧时清除在途标记（onIdle 入口 / onSettled 兜底）。 */
+export function clearTurnInflight(sessionId, taskId) {
+    const session = sessions.get(sessionId);
+    session?.inflightTurns?.delete(taskId);
+}
+/** session 内是否仍有 turn 在流式输出（未 idle）。 */
+function hasInflightTurn(sessionId) {
+    const session = sessions.get(sessionId);
+    return (session?.inflightTurns?.size ?? 0) > 0;
+}
 // ─── SessionKey ↔ SessionId 索引 ──────────────────────────────
 /**
  * 绑定 openclaw sessionKey 到首条消息的 A2A 身份。
@@ -354,15 +378,33 @@ export function clearWaitState(sessionId, reason, taskId) {
 }
 // ─── Subagent 最终交付（收拢自原 outbound.deliverSubagentFinalResult） ──
 /**
- * 当所有 subagent 完成且父 turn 已 settle 时，由 manager 发送唯一的
- * final 帧并真正结束当前 A2A session：
- *   1. 合并 completionTexts 发送 final:true 帧
+ * 当所有 subagent 完成且父 turn 已 settle 时，由 manager 发送终态帧并真正
+ * 结束当前 A2A session：
+ *   1. completed 状态帧（"任务处理已完成~"）→ final:true 全文本帧（合并
+ *      completionTexts）——与 reply-dispatcher 正常终态同序，xy_tester
+ *      与客户端依赖该顺序
  *   2. 清理等待态、停止心跳、移除任务链
  *   3. 会话状态迁移到 completed
  */
 export async function deliverSubagentFinalResult(params) {
     const { state, reason } = params;
     const log = logger.withContext(state.sessionId, state.taskId);
+    // 🔑 幂等 guard：终态交付只执行一次。onIdle defer 分支 / onSettled 安全网 /
+    // subagent_ended hook 可能相继触发交付，重复调用为 no-op。
+    // （检查与下方 finalDeliveryStarted 置位之间无 await，不会并发穿透。）
+    if (state.finalDeliveryStarted) {
+        log.log(`[SUBAGENT-FINAL] Final delivery already started, skipping duplicate trigger, reason=${reason}`);
+        return;
+    }
+    // 🔑 时机门控：session 内仍有 turn 在流式输出（steer 重分发的新 turn 未
+    // idle）时推迟交付 —— 此时以最新 taskId 发 final:true 会提前截断在途
+    // 回复，且新 turn 之后还会再发一次 final（双重终态帧）。推迟期间
+    // waitState 完整保留（parentSettled、完成计数等就绪态不丢失），由在途
+    // turn 的 onIdle defer 分支或 onSettled 安全网就地交付，身份仍取任务链末尾。
+    if (hasInflightTurn(state.sessionId)) {
+        log.log(`[SUBAGENT-FINAL] Deferring final delivery — turn still in flight, reason=${reason}`);
+        return;
+    }
     const config = getCachedXYConfig();
     if (!config) {
         log.error(`[SUBAGENT-FINAL] No cached XY config, cannot deliver final result`);
@@ -375,17 +417,56 @@ export async function deliverSubagentFinalResult(params) {
         ? state.completionTexts.join("\n\n")
         : (params.text || undefined) ?? "子任务已完成";
     setSessionState(state.sessionId, "completing");
-    await sendA2AResponse({
+    // final 帧走会话出站队列：排在任何在途 partial 帧之后，保证客户端
+    // 先收齐流式正文再收到 final（与 reply-dispatcher 的终态帧同一收口点）。
+    // 终态帧延迟同 reply-dispatcher 的 terminalFrameDelayMs 治理：让已发出的
+    // 长正文先穿过下游服务端慢速管道，保证终态帧最后到达。
+    // 解析下发帧所用的 A2A 身份：跟随任务链末尾的最新 taskId/messageId。
+    // steer 重分发场景下 state.taskId 为旧身份，取链尾可保证终态帧与
+    // 心跳/保活帧的 taskId 一致，客户端不会看到 taskId 跳跃。
+    const effectiveTaskId = getCurrentTaskId(state.sessionId) ?? state.taskId;
+    const effectiveMessageId = getCurrentMessageId(state.sessionId) ?? state.messageId;
+    const terminalFrameDelayMs = config.terminalFrameDelayMs ?? 0;
+    const session = sessions.get(state.sessionId);
+    const sendCompletedStatus = () => sendStatusUpdate({
+        config,
+        sessionId: state.sessionId,
+        taskId: effectiveTaskId,
+        messageId: effectiveMessageId,
+        text: "任务处理已完成~",
+        state: "completed",
+    });
+    const sendFinal = () => sendA2AResponse({
         config,
         sessionId: state.sessionId,
-        taskId: state.taskId,
-        messageId: state.messageId,
+        taskId: effectiveTaskId,
+        messageId: effectiveMessageId,
         text: finalText,
         append: false,
         final: true,
     });
+    if (session) {
+        session.outboundQueue.enqueue({
+            taskId: effectiveTaskId,
+            label: "subagent-terminal-status",
+            delayMs: terminalFrameDelayMs,
+            send: sendCompletedStatus,
+        });
+        session.outboundQueue.enqueue({
+            taskId: effectiveTaskId,
+            label: "subagent-final",
+            delayMs: terminalFrameDelayMs,
+            send: sendFinal,
+        });
+        await session.outboundQueue.whenIdle();
+    }
+    else {
+        await sendCompletedStatus();
+        await sendFinal();
+    }
     clearWaitState(state.sessionId, reason ?? "all-subagent-results-delivered", state.taskId);
-    completeTask(state.sessionId, state.taskId);
+    // 清理整个任务链（无 expectedTaskId），避免 steer 引入的额外 taskId 残留。
+    completeTask(state.sessionId);
     setSessionState(state.sessionId, "completed");
-    log.log(`[SUBAGENT-FINAL] Subagent final delivered to original A2A task, reason=${reason}`);
+    log.log(`[SUBAGENT-FINAL] Subagent final delivered, reason=${reason}, effectiveTaskId=${effectiveTaskId}`);
 }

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

@@ -1,3 +1,5 @@
+import { StreamAssembler } from "./stream-assembler.js";
+import { OutboundQueue } from "./outbound-queue.js";
 export interface TaskEntry {
     taskId: string;
     messageId: string;
@@ -39,6 +41,20 @@ export interface ConversationSession {
     subagentWaits: SubagentWaitState[];
     /** manager 拥有的 30s 状态心跳定时器。 */
     statusTimer?: NodeJS.Timeout;
+    /**
+     * 当前 dispatcher 的流式文本装配器（model/injected 段拼接 + 权威文本修正）。
+     * 生命周期随 dispatcher：dispatcher 创建时挂载，终态清理时卸载；
+     * 挂在这里是为了让工具（display-a2ui-card 等）经 getSession 注入文本段。
+     */
+    assembler?: StreamAssembler;
+    /** 会话级出站队列：所有出站帧的时序收口点，生命周期随 session。 */
+    outboundQueue: OutboundQueue;
+    /**
+     * 在途 turn 的 taskId 集合（dispatch 时登记，onIdle/onSettled 时清除）。
+     * subagent 终态帧的时机门控据此判断"session 内仍有 turn 在流式输出"，
+     * 防止 final:true 提前截断在途回复（steer 重分发场景）。
+     */
+    inflightTurns: Set<string>;
     lastActivityAt: number;
 }
 export declare function createConversationSession(sessionId: string): ConversationSession;

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

@@ -6,12 +6,17 @@
 //   - sessionKey:   openclaw 路由 sessionKey（吸收自 sessionKeyMap）
 //   - subagentWaits: subagent 等待态（吸收自 subagent-wait-state）
 //   - statusTimer:  30s 状态心跳定时器（由 manager 拥有）
+//   - assembler:    流式文本装配器（model/injected 段拼接 + 权威文本修正）
+//   - outboundQueue: 会话级出站 FIFO（帧时序唯一收口，coalescing/delayMs）
+import { OutboundQueue } from "./outbound-queue.js";
 export function createConversationSession(sessionId) {
     return {
         sessionId,
         state: "working",
         tasks: [],
         subagentWaits: [],
+        outboundQueue: new OutboundQueue(sessionId),
+        inflightTurns: new Set(),
         lastActivityAt: Date.now(),
     };
 }

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

@@ -1,25 +1,50 @@
 import type { XYChannelConfig } from "../types.js";
-/** 关闭当前 cron turn（清理全部定时器）。 */
-export declare function closeCronTurn(reason: string): void;
+/** 随 push 下发的 cron 元数据（jobId + title），客户端据此识别 push 来源。 */
+export interface CronTurnMeta {
+    jobId?: string;
+    jobTitle?: string;
+}
+/** 关闭指定 job 的 cron turn（清理全部定时器）。 */
+export declare function closeCronTurn(jobId: string | undefined, reason: string): void;
 /**
  * cron turn 开始检测。由 provider.ts 在识别到 [cron:...] 首条消息时调用。
  * 同一 cron run 的每次模型调用都会重复触发检测 —— 此时仅刷新安全定时器，
  * 不重开 turn（避免 churn，也避免重置 agentEnded/缓冲状态）。
+ * 按 jobId 隔离：不同 job 并发触发时各自独立建 turn，后到 job 的 jobId
+ * 不再被覆盖丢弃。
  */
-export declare function notifyCronDetected(jobId?: string): void;
+export declare function notifyCronDetected(jobId?: string, jobTitle?: string): void;
 /**
  * cron run 结束信号（lifecycle phase=end，由 index.ts 的 agent event
- * subscription 调用）。进入 announce 宽限期：
+ * subscription 调用，jobId 从 event.sessionKey 解析）。只结束该 job 的
+ * turn，进入 announce 宽限期：
  *   - 宽限期内 announce 到达 → 放行（见 gateCronSendText）；
  *   - 宽限期结束无 announce → 合并缓冲文本发一条（路径 B）。
+ * jobId 缺失（sessionKey 解析失败）时：若恰有 1 个活跃 turn，兼容旧单槽
+ * 行为结束之；多个活跃 turn 时无法归属，跳过并告警。
  */
-export declare function notifyCronAgentEnd(): void;
+export declare function notifyCronAgentEnd(jobId?: string): void;
 export type CronSendTextGate = "swallow" | "announce" | "none";
+export interface CronGateResult {
+    gate: CronSendTextGate;
+    /**
+     * gate === "announce" 时的 cron 元数据同步快照（其余情况为 null）。
+     * 快照在 gate 返回时完成 —— 调用方后续 await 空窗期内 turn 可能被
+     * safety timer 关闭，届时再读 turn 已拿不到 meta。
+     */
+    meta: CronTurnMeta | null;
+    /** 本次 sendText 归属的 cron jobId（调用方据此精确关闭 turn）。 */
+    jobId?: string;
+}
 /**
- * sendText 闸门：
- * - "swallow"：cron turn 进行中（run 未结束），吞掉中间 sendText，文本入缓冲；
- * - "announce"：run 已结束（宽限期内），当前 sendText 是 announce 最终
- *   结果，放行（唯一一条，缓冲丢弃）；
- * - "none"：无 cron turn，正常发送。
+ * sendText 闸门。sendText 层拿不到 jobId/runId，只能凭 announceLike
+ * （to 是否为 DEFAULT_PUSH_MARKER，即是否有显式 target）做粗路由：
+ * - announceLike（无 target）：run 结束后的 announce 最终结果，路由到处于
+ *   agentEnded 宽限的 turn。多个 ended turn（两端几乎同时结束的窄竞态）按
+ *   endedAt FIFO，与 openclaw 按 run 完成顺序投递 announce 一致。
+ * - 非 announceLike（有 target）：run 期间的中间 sendText，吞入活跃 turn
+ *   缓冲。恰 1 个活跃 turn 正常吞；多活跃 turn（真并发、无法归属）安全回退
+ *   返回 "none"（不聚合、原样发送，宁可多推也不让 pushText/cronId 串台）。
+ * - "none"：无 cron turn 或无法归属，按普通 push 发送。
  */
-export declare function gateCronSendText(swallowedText?: string, config?: XYChannelConfig): CronSendTextGate;
+export declare function gateCronSendText(swallowedText: string | undefined, announceLike: boolean, config?: XYChannelConfig): CronGateResult;