@ai-setting/roy-agent-core 1.7.85 → 1.7.89

package/dist/env/event-source/types.d.ts

@@ -134,6 +134,33 @@ export interface EventSourceConfig {
      *    里手动开启，否则 consumer 能 ready 但永远收不到事件。
      */
     eventKeys?: string[];
+    /**
+     * ★ Task #5360（补充需求 2026-11-11 20:54）：是否推送「状态通知文本消息」。
+     *
+     * ## 背景
+     *
+     * 卡片化改造后，rule-based 直发的状态文本（`⏱️ 后台任务运行中 20m` /
+     * `✅ 已完成 36m`）默认下线，改由任务卡片承载。本开关是**逃生舱**：
+     * 保留旧的文本推送能力，用户想恢复时一行配置即可，不必 revert 代码。
+     *
+     * ## 取值
+     *
+     * - `false` / **缺省**（默认）：不发状态通知文本 —— 全部走卡片
+     * - `true`：逐字恢复改造前的文本推送行为
+     *
+     * ## 边界（很重要，别扩大语义）
+     *
+     * - 只影响「状态通知文本」，**不影响卡片**（卡片是渠道独立插件，与本开关正交）
+     * - 不影响 `sink === "stdout"` 的 CLI 本地输出（本地没有卡片可发，
+     *   文本是唯一可见输出 —— 见 `shouldDeliverNoticeText` 的 stdout 例外）
+     * - 不影响卡片失败兜底 markdown 与失败回执（那是**降级/异常告知**，不是状态通知）
+     *
+     * ## 类型严格性
+     *
+     * 判定处一律用 `=== true`，所以手改 JSON 写出 `"true"`（字符串）/ `1` /
+     * `null` 都会被当成 `false` —— 防 YAML/手改造成的类型漂移。
+     */
+    statusNotifications?: boolean;
     /** 轮询间隔（毫秒，定时器用） */
     interval?: number;
     /** cron 表达式（定时器用） */
@@ -193,6 +220,31 @@ export interface EventSourceConfig {
      * 回退为 legacy。
      */
     channelPromptMode?: "legacy" | "lean";
+    /**
+     * ★ Task #5333 — 该事件源驱动的 agent 会话**额外注入**的工具名列表。
+     *
+     * 背景（用户 2026-11-11 16:54）：「ES config 支持 extend tools ——
+     * 不同 ES 驱动的 agent 注入 tools 可不同。企微 ES 有特有工具
+     * （wecom_respond），不该配到 default agent。」
+     *
+     * 语义：
+     * - 只有 `tool.metadata.channelOnly === true` 的工具受本字段控制
+     *   （未标记 channelOnly 的工具对所有 agent 本来就可见，无需声明）
+     * - 未配置本字段 → 不放行任何 channelOnly 工具
+     * - 配置后 → handler 把它写进 `evt.metadata.extendTools`，
+     *   经 run.ts / run-headless-dispatch.ts 透传到
+     *   `AgentContext.extendTools`，最终由 ToolRegistry / AgentComponent
+     *   的可见性过滤放行
+     *
+     * 内置默认：`wecom-cli` handler 恒注入 `["wecom_respond"]`
+     * （企微唯一出站工具，不配也必须可见），用户的 config.extendTools
+     * 追加在后并去重。
+     *
+     * ```json
+     * { "type": "wecom-cli", "extendTools": ["my_extra_tool"] }
+     * ```
+     */
+    extendTools?: string[];
     /**
      * Agent IM 地址（bounty-im 类型用，格式：agent-id@host）
      *
@@ -753,7 +805,7 @@ export interface BuildNotifyHandlePromptInput {
         error?: string;
         /**
          * 子 session ID —— 超时 / 失败后如需**续跑**，主 agent 可直接
-         * `delegate_task(existingSubSessionId=<此值>, ...)` 让子代理继承历史继续推进，
+         * `delegate_task(sub_session_id="<此值>", ...)` 让子代理继承历史继续推进，
          * 不必从零重来。
          */
         subSessionId?: string;

package/dist/env/event-source/wecom-card-action-handler.d.ts

@@ -24,9 +24,21 @@
  * 回调原样带回 → 用前缀 `roy-task-` 反解出数字任务号。
  * 非 roy-task 前缀（外部卡片）→ taskId=null，动作不执行。
  */
-import { type WecomMilestoneLite } from "./wecom-card-builder";
-/** 卡片动作类型 */
-export type WecomCardAction = "view" | "mark_done" | "reopen";
+import { type WecomActivityLike, type WecomMilestoneLite } from "./wecom-card-builder";
+import type { WecomSessionCardState } from "../task/plugins/wecom-session-card-store";
+import type { ActivityProbeResult } from "../task/plugins/sub-session-activity";
+/**
+ * 卡片动作类型
+ *
+ * ★ Task #5360：新增 `refresh_activity`（刷新 sub-session 活性）。
+ *
+ * 与 `view`（刷操作时间线）分开，因为企微 `horizontal_content_list` 只有
+ * 6 条预算且已被时间线占满 —— 见 wecom-card-builder 的
+ * `WecomCardActionKey.REFRESH_ACTIVITY` 注释。
+ *
+ * ★ Task #5419：新增 `create_lark_group`（建关联飞书群，对齐飞书）。
+ */
+export type WecomCardAction = "view" | "mark_done" | "reopen" | "refresh_activity" | "create_lark_group";
 /** 解析出的卡片动作事件 */
 export interface WecomCardActionEvent {
     /** 用户点的按钮 key（WecomCardActionKey 之一或外部自定义） */
@@ -35,6 +47,11 @@ export interface WecomCardActionEvent {
     cardTaskId: string;
     /** 反解出的任务号；非 roy-task 前缀 → null */
     taskId: number | null;
+    /**
+     * ★ 补充需求（22:31）：反解出的 sub-session id（`roy-session-` 前缀）。
+     * 与 `taskId` 互斥：一张卡要么挂 task，要么挂 session。
+     */
+    sessionId: string | null;
     /** 操作者 userid */
     userId: string;
     /** 回调帧 req_id（更新帧必须原样透传） */
@@ -56,10 +73,54 @@ export interface WecomCardActionPorts {
     updateCard: (reqId: string, cardTaskId: string, statusLabel: string, note?: string, timeline?: WecomMilestoneLite[], action?: WecomCardAction, 
     /**
      * ★ Task #5273：任务号+标题（可选，渲染进更新卡 main_title）
+     * ★ Task #5360：`activity` —— sub-session 活性
+     *   （`undefined` = 不渲染；`null` = 查了但没数据，渲染「暂无数据」）
      */
     extra?: {
         taskNumber?: number;
         taskTitle?: string;
+        activity?: WecomActivityLike | null;
+        /** ★ Task #5360（CV MAJOR-2）：任务是否已终态（决定 ⚪已结束 vs 🔴疑似停滞） */
+        activityTerminal?: boolean;
+    }) => Promise<void>;
+    /**
+     * ★ Task #5364（B 方案）：用**完整快照**刷新 session 卡。
+     *
+     * 与 `updateCard` 的区别：那个是 task 卡的通用更新（statusLabel/timeline/
+     * activity 三个松散参数）；本端口接收一次完整的 session 快照，由实现方
+     * 调 `buildWecomSessionCardUpdateBody` 渲染「生命周期 + 会话详情 + 任务 +
+     * 操作记录 + 活性」一整套。
+     *
+     * 未注入 ⇒ 自动降级到 `updateCard`（#5360 行为，仅活性）。
+     */
+    updateSessionCard?: (reqId: string, input: {
+        sessionId: string;
+        /** 回调带回的原始 task_id（刷新帧必须原样回填） */
+        cardTaskId: string;
+        /** 持久层快照；undefined = 无记录（降级仅活性） */
+        state?: WecomSessionCardState;
+        /** 实时活性；null = 查了但没数据 */
+        activity: WecomActivityLike | null;
+        /**
+         * ★ Task #5419：session 关联的任务信息（刷新增强）。
+         * undefined = 无任务 / 端口未注入。
+         */
+        task?: {
+            id: number;
+            title?: string;
+            status?: string;
+            progress?: number;
+            milestones?: WecomMilestoneLite[];
+        };
+        /**
+         * ★ Task #5419：已关联飞书群 chatId（建群后刷新帧带群链接）。
+         */
+        perTaskChatId?: string;
+        /**
+         * ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title）。
+         */
+        errorHint?: string;
+        now?: number;
     }) => Promise<void>;
     /**
      * ★ Task #5203：读任务的操作时间线（milestones + processSteps）。
@@ -84,6 +145,118 @@ export interface WecomCardActionPorts {
         title?: string;
         number?: number;
     } | undefined>;
+    /**
+     * ★ Task #5360：读 sub-session 活性（「刷新活性」动作用）。
+     *
+     * 与飞书侧 `CardActionPorts.loadSubSessionActivity` **同一个 probe 实现**
+     * （`createActivityProbe`），避免两渠道 liveness 阈值漂移。
+     *
+     * 不注入 / 抛错 / undefined ⇒ 卡片渲染「暂无数据」，绝不阻断更新。
+     */
+    loadSubSessionActivity?: (taskId: number) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ 补充需求（22:31）：**session-only** 活性读取（无 task 场景）。
+     *
+     * 与 `loadSubSessionActivity(taskId)` 的区别：后者要从 task 反查 bgTask；
+     * 本端口**直达** session store —— 因为回调里直接带着 sessionId，
+     * 而这条链上根本没有 task。
+     */
+    loadSessionActivity?: (sessionId: string) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ Task #5364（B 方案）：读 **session 卡持久层**快照。
+     *
+     * ## 为什么刷新必须走它（而不是内存 / task）
+     *
+     * B 方案下「后续 lifecycle 不主动 patch，只写持久层」，所以**刷新是唯一
+     * 能看到最新状态的时机**。快照里带着：
+     * - `lifecycle`（超时 / 完成 / 失败 / 停止 —— 单靠活性推不出来）
+     * - `title` / `agentType` / `startedAt` / `associatedTaskId`（首次发卡的信息）
+     * - `milestones`（这一路的状态轨迹）
+     * - `cardTaskId`（刷新帧必须原样回填，否则协议拒绝）
+     *
+     * 读内存 map 的话进程重启就全丢；读 task 的话没有 task 的 session 全丢。
+     *
+     * 不注入 / 抛错 / undefined ⇒ 降级为「只有活性」的刷新卡（**仍更新卡片**，
+     * 用户点了按钮必须有反馈）。
+     */
+    loadSessionCardState?: (sessionId: string) => WecomSessionCardState | undefined | Promise<WecomSessionCardState | undefined>;
+    /**
+     * ★ Task #5418：按 roy 任务号反查 session 卡持久层记录。
+     *
+     * task 卡刷新路径回退 session probe 时需要 sessionId ——
+     * `roy-task-` 前缀卡回调里没有 sessionId，唯一持久化来源是
+     * `wecom_session_card.associated_task_id`。注入方（wecom-cli-handler）
+     * 用 `store.list()` 扫描；缺省 ⇒ 不回退（行为同旧版）。
+     */
+    findSessionCardByTaskId?: (taskId: number) => WecomSessionCardState | undefined | Promise<WecomSessionCardState | undefined>;
+    /**
+     * ★ Task #5419：session → task 反查 + 全量任务信息（刷新增强）。
+     *
+     * 用户 2026-11-13：「有刷新详情按钮可以刷新 subsession 状态
+     * （包括是否建任务，以及任务名称和动态，也包括 subsession 的
+     * 消息数）」。
+     *
+     * 生产接线（wecom-cli-handler）：`TaskComponent.getTaskIdBySessionId`
+     * （task_operation.session_id 反查）+ `getTaskWithOperations`。
+     *
+     * 返回 undefined = 该 session 没建任务（卡上不渲染任务行）；
+     * 抛错 = 降级（不阻断刷新）。
+     */
+    loadSessionTaskInfo?: (sessionId: string) => Promise<{
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+        milestones?: WecomMilestoneLite[];
+    } | undefined> | {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+        milestones?: WecomMilestoneLite[];
+    } | undefined;
+    /**
+     * ★ Task #5419：建**关联飞书群**（对齐飞书 handleGroupActionSessionOnly）。
+     *
+     * 生产接线（wecom-cli-handler）：lark-cli +chat-create +
+     * SessionComponent.attachGroupSession（独立群 session + 1 条
+     * user 背景事件 + metadata linkedFromSessionId）。
+     *
+     * 返回新群 chatId；抛错 = 建群失败（结果翻失败，但卡片仍更新）。
+     */
+    createLarkGroupForSession?: (sessionId: string) => Promise<string>;
+    /**
+     * ★ Task #5419：读该 session 已关联的飞书群（幂等防重复建群）。
+     *
+     * 生产接线：`SessionComponent.findGroupChatForSession`
+     * （扫 metadata linkedFromSessionId，与飞书侧同源）。
+     * 未注入 / 抛错 ⇒ 当作没有群（可能重复建，但不崩）。
+     */
+    findGroupChatForSession?: (sessionId: string) => Promise<{
+        chatId: string;
+    } | undefined> | {
+        chatId: string;
+    } | undefined;
+    /**
+     * ★ Task #5419：建群成功后发一条企微消息带飞书群 applink。
+     *
+     * 用户：「建完可以展示或者发一条企微消息带上飞书群跳转链接哈」。
+     * best-effort：抛错不阻断建群结果。
+     */
+    notifyGroupLink?: (input: {
+        sessionId: string;
+        chatId: string;
+        /** 群名（可选，消息文案用） */
+        chatName?: string;
+        /**
+         * ★ CV 5419 BLOCKER-1：点击按钮的**企微用户** userid。
+         *
+         * 通知消息必须发给企微侧（不是飞书群 —— chatId 是
+         * 飞书群 id，企微 CLI 不认）。缺省时实现方从 session
+         * store 的 chatId 兜底。
+         */
+        userId?: string;
+    }) => Promise<void>;
 }
 /** 处理结果 */
 export interface WecomCardActionResult {
@@ -91,6 +264,11 @@ export interface WecomCardActionResult {
     /** 执行的动作（解析失败时缺省） */
     action?: WecomCardAction;
     error?: string;
+    /**
+     * ★ Task #5419：create_lark_group 成功时的新群 chatId
+     * （幂等命中时 = 已有群 chatId）。
+     */
+    newChatId?: string;
 }
 /** 测试钩子：清空 in-flight 去重表（仅供单测 beforeEach 使用） */
 export declare function __resetWecomCardActionInflightForTest(): void;
@@ -135,6 +313,60 @@ export declare function buildWecomCardUpdateBody(input: {
      */
     taskTitle?: string;
     taskNumber?: number;
+    /**
+     * ★ Task #5360：sub-session 活性
+     * （`undefined` = 不渲染；`null` = 暂无数据）
+     */
+    activity?: WecomActivityLike | null;
+    /** ★ Task #5360（CV MAJOR-2）：任务是否已终态 */
+    activityTerminal?: boolean;
+}): {
+    cmd: string;
+    body: Record<string, unknown>;
+};
+/**
+ * ★ Task #5364（B 方案）—— 构造 **session 卡刷新**的更新帧。
+ *
+ * 独立导出（不走 ports）是为了：
+ * 1. 单测能直接断言渲染结果，不依赖 bridge
+ * 2. `WecomCliInstance` 的 `updateSessionCard` 实现只需要两步：
+ *    `buildWecomSessionCardUpdateBody(...)` → `sendFrameWithReqId`
+ *
+ * ## 为什么快照允许 `undefined`
+ *
+ * B 方案里持久层是「刷新时的唯一数据源」，但它可能不存在（进程刚重启 +
+ * 首次事件丢了 store / 老卡片）。此时**不能不给反馈** —— 用户点了按钮，
+ * 什么都没变比显示「暂无数据」更糟。所以降级路径渲染：状态=「状态未知」+
+ * 活性（活性反而是这时最有用的信号）。
+ */
+export declare function buildWecomSessionCardUpdateBody(input: {
+    /** 回调带回的原始 task_id（原样回填，协议硬约束） */
+    cardTaskId: string;
+    sessionId: string;
+    /**
+     * req_id（协议必填）。命名带 ForTest 是历史遗留：生产路径由
+     * `updateSessionCard` 端口在 `sendFrameWithReqId` 时注入 headers，
+     * 这里仅用于单测直接验证帧结构。
+     */
+    reqIdForTest?: string;
+    /** 持久层快照；undefined = 无记录 */
+    state?: WecomSessionCardState;
+    /** 活性；undefined = 不渲染该块，null = 暂无数据 */
+    activity?: WecomActivityLike | null;
+    now?: number;
+    /** 关联任务（可选覆盖；缺省从 state.associatedTaskId 推导编号） */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /**
+     * ★ Task #5419：已关联飞书群 chatId（渲染「飞书群」行）。
+     */
+    perTaskChatId?: string;
+    /** ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title） */
+    errorHint?: string;
 }): {
     cmd: string;
     body: Record<string, unknown>;

package/dist/env/event-source/wecom-card-builder.d.ts

@@ -35,14 +35,44 @@
  * @see wecom-ws-bridge.ts（帧发送）
  * @see wecom-task-notify-plugin.ts（hook 接线）
  */
+import { type SubSessionActivity } from "../task/plugins/sub-session-activity";
+/** 企微侧活性入参别名（与飞书侧同名类型，语义一致） */
+export type WecomActivityLike = SubSessionActivity;
 /** 标准按钮动作 key（回调 event_key 据此分发） */
 export declare const WecomCardActionKey: {
-    /** 查看详情 */
+    /** 查看详情（刷操作时间线） */
     readonly VIEW: "task_view";
     /** 标记完成 */
     readonly MARK_DONE: "task_mark_done";
     /** 重新打开 */
     readonly REOPEN: "task_reopen";
+    /**
+     * ★ Task #5360：刷新 sub-session 活性（消息数 + 最近一条消息）。
+     *
+     * ## 为什么与 VIEW 分成两个按钮（而不是把活性塞进「刷新详情」）
+     *
+     * 企微 `horizontal_content_list` 协议上限 **6 条**（`MAX_HORIZONTAL_ROWS`），
+     * 而进展/更新卡的 6 条已经被「状态 + 5 条操作时间线」占满。把活性挤进去
+     * 必然挤掉操作时间线 —— 直接违反用户「之前展示的信息一个都不能少」。
+     *
+     * 所以：`task_view` 管时间线（旧语义零变更），`task_refresh_activity`
+     * 管活性（走 quote_area，不占 horizontal 预算）。
+     */
+    readonly REFRESH_ACTIVITY: "task_refresh_activity";
+    /**
+     * ★ Task #5419：建**关联飞书群**（对齐飞书 #5403/#5397）。
+     *
+     * 用户 2026-11-13：「另外也有按钮进行飞书建群哈，功能跟飞书一样，
+     * 建关联飞书群，建完可以展示或者发一条企微消息带上飞书群跳转链接哈」
+     *
+     * ## 为什么企微卡可以有「飞书群」按钮
+     *
+     * wecom-card-builder 旧注释（#5360）说「企微侧本来就没有 per-task
+     * 群概念」—— 那指的是**企微群**。#5403 之后建群的目标是
+     * **飞书群**（群 session 独立 + 注入背景事件），与企微群概念
+     * 正交：企微只是「遥控器」，群在飞书侧。
+     */
+    readonly CREATE_LARK_GROUP: "task_create_lark_group";
 };
 export type WecomCardActionKey = (typeof WecomCardActionKey)[keyof typeof WecomCardActionKey];
 /** 企微按钮 style：1 默认蓝 / 2 次要灰 / 3 / 4 强调（官方 1~4） */
@@ -117,6 +147,33 @@ export interface WecomButtonInteractionCard {
  *   更新帧的 task_id 必须原样用回调带回的值
  */
 export declare function wecomCardTaskIdForTask(taskId: number): string;
+/**
+ * ★ 补充需求（22:31）：**session 卡**的稳定 task_id 前缀。
+ *
+ * 与 `roy-task-` 并列 —— 回调时用它区分「这张卡挂在 task 上」还是
+ * 「挂在 sub-session 上」。两种前缀互不包含（`roy-task-` vs `roy-session-`），
+ * 反解无歧义。
+ */
+export declare const ROY_SESSION_PREFIX = "roy-session-";
+/**
+ * 造 session 卡的稳定 task_id。
+ *
+ * ## 格式（★ 澄清 22:37：session 是主键，task 是附加值）
+ *
+ * ```
+ * roy-session-<sessionId>                ← 无关联 task
+ * roy-session-<sessionId>@task-<taskId>  ← 有关联 task
+ * ```
+ *
+ * 用 `@task-` 而不是再嵌前缀：企微 task_id 字符集限定「数字字母和 `_-@`」，
+ * `@` 合法；且 `roy-session-` 与 `roy-task-` 本来就互斥，反解无歧义。
+ *
+ * ⚠️ 反解时**只取 sessionId 部分**（task 段仅用于诊断/未来扩展）——
+ * 刷新永远读 session store，这是本次澄清的核心。
+ */
+export declare function wecomCardTaskIdForSession(sessionId: string, taskId?: number): string;
+/** session 卡 task_id 里「附加 task 段」的分隔符 */
+export declare const WECOM_SESSION_TASK_SEP = "@task-";
 /**
  * 生成一张新卡的 task_id：`roy-task-<taskId>-<seq>-<rand>`。
  *
@@ -158,6 +215,72 @@ export declare function buildWecomButtonInteractionCard(input: {
     /** 已有的 task_id（更新场景复用；发新卡时不传自动生成） */
     cardTaskId?: string;
 }): WecomButtonInteractionCard;
+/** session 层生命周期（与飞书侧同义） */
+export type WecomSessionLifecycle = "running" | "completed" | "timeout" | "failed" | "stopped";
+/**
+ * ★ Task #5364（DS review R1 MAJOR-2）—— **刷新帧**用的生命周期。
+ *
+ * 比 `WecomSessionLifecycle` 多一个 `unknown`：刷新时若持久层没有该
+ * session 的记录（进程重启 / store 读失败 / 更早版本发的卡），我们
+ * **不知道**它是什么状态。此时必须如实说「未知」而不是乐观地报
+ * 「运行中」—— 后者会和活性侧的 🔴 疑似停滞 同时出现在一张卡上，
+ * 给用户两个互相矛盾的信号。
+ */
+export type WecomSessionUpdateLifecycle = WecomSessionLifecycle | "unknown";
+/**
+ * ★ Task #5360（用户明令「企微也是这个逻辑」）—— 构造**企微 session 卡**。
+ *
+ * ## 与 task 卡的关系：并列，共用零件
+ *
+ * 不复用 `buildWecomButtonInteractionCard` 的原因：那个签名是
+ * `taskId: number`（必填）+ `buildWecomTextNoticeCard` 的进度百分比语义，
+ * session 没有 task 号也没有「进度 %」。硬塞会渲染出 `Task #0` / `0%` 这类噪音。
+ *
+ * 共用的是：`WecomButtonInteractionCard` 结构、按钮裁剪、`formatActivityQuote`
+ * （⇒ 活性阈值与文案与飞书/企微 task 卡**完全一致**，不会出现同一个
+ * session 在两个渠道颜色不同）。
+ *
+ * ## 主键
+ *
+ * `task_id = roy-session-<sessionId>[@task-<n>]` —— 回调时
+ * `parseRoySessionId` 反解出干净的 sessionId，刷新走 session 主键路径。
+ *
+ * ## 建群按钮（★ Task #5419 更新）
+ *
+ * #5360 时企微侧没有建群按钮（当时建群目标是企微群，确实没有）。
+ * #5403 之后建群目标改为**飞书群**（独立群 session + 背景事件），
+ * 企微卡只是遥控入口 —— 用户 2026-11-13 明令「也有按钮进行飞书
+ * 建群哈，功能跟飞书一样」。故 session 卡无条件渲染「建飞书群」。
+ */
+export declare function buildWecomSessionCard(input: {
+    /** ★ 主键：sub-session id */
+    sessionId: string;
+    /** session 层生命周期（★ 与有无 task 无关） */
+    lifecycle?: WecomSessionLifecycle;
+    /** 会话标题（描述 / agent 名）；缺省用 sessionId 截断 */
+    title?: string;
+    /** 所属 agent（subagentType） */
+    agentType?: string;
+    /** 开始时间（ISO） */
+    startedAt?: string;
+    /** 已运行时长（人类可读） */
+    elapsedText?: string;
+    /**
+     * ★ 该 session 内创建的 task（可选增强）。
+     * 有 → 卡上多一行任务信息；无 → 只显示 session 活性。
+     */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /** 活性快照。undefined = 不渲染；null = 暂无数据 */
+    activity?: WecomActivityLike | null;
+    activityNow?: number;
+    /** 执行动态（会话级里程碑） */
+    milestones?: WecomMilestoneLite[];
+}): WecomButtonInteractionCard;
 /**
  * 构造 aibot_send_msg 直发 template_card 帧。
  *
@@ -211,6 +334,89 @@ export declare function buildWecomCardUpdateFrame(input: {
     taskTitle?: string;
     /** ★ Task #5273：roy 任务号（可选，与 taskTitle 配对渲染） */
     taskNumber?: number;
+    /**
+     * ★ Task #5360：sub-session 活性（用户点「刷新活性」时传入）。
+     *
+     * - `undefined` → 不渲染活性（普通 view / mark_done，行为与改造前一致）
+     * - `null`      → 渲染「暂无数据」（用户点过了，必须有反馈）
+     * - 快照        → 渲染信号灯 + 消息数 + 最近消息
+     */
+    activity?: WecomActivityLike | null;
+    /** ★ Task #5360：活性时间基准（注入便于测试；缺省 Date.now()） */
+    activityNow?: number;
+    /** ★ Task #5360：任务是否终态（决定报「已结束」而非「疑似停滞」） */
+    activityTerminal?: boolean;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};
+/**
+ * ★ Task #5364（用户 2026-11-12 08:34 拍板 B）——
+ * 构造 **session 卡的更新帧**（`aibot_respond_update_msg`）。
+ *
+ * ## 为什么需要它（B 方案的落点）
+ *
+ * 企微协议：`aibot_respond_update_msg` 只能在 `template_card_event` 回调的
+ * 5 秒窗口内、用回调带回的 `req_id` 发。生命周期事件没有 req_id ⇒ **无法主动
+ * patch**。所以「一张卡承载整个生命周期」只能靠**用户点按钮把窗口打开**。
+ *
+ * ⇒ 这张帧必须在**一次渲染里装齐全部信息**（这是用户唯一能看到的最新快照）：
+ *
+ * | 信息 | 来源 | 为什么不能省 |
+ * |------|------|--------------|
+ * | 生命周期状态 | store.lifecycle | 用户要知道「跑完了没 / 是超时还是失败」 |
+ * | 会话详情（id/agent/已运行） | store + startedAt | 首次发卡时的信息，刷新不能擦掉 |
+ * | 任务增强（Task #id/title/status） | store.associatedTaskId → task | 有 task 时后端不再发 task 卡，信息必须在这 |
+ * | 操作记录（milestones 时间线） | store.milestones | 「这一路发生了什么」 |
+ * | 活性（消息数 + 最近 msg） | 实时 probe | 判断 LLM 有没有真在推进 |
+ *
+ * ## 与 `buildWecomSessionCard`（首发帧）的关系
+ *
+ * 同一套排版口径（生命周期文案表 / 行裁剪 / `formatActivityQuote`），
+ * 但它是**整卡替换**（update 帧的 schema 要求），所以这里重新组装一份，
+ * 而不是复用首发卡的返回值 —— 首发卡是 `aibot_send_msg` 的 body 形状。
+ *
+ * @param input.reqId 回调带回的 req_id（**必须**，缺失直接抛）
+ * @param input.cardTaskId 回调带回的原始 `template_card.task_id`（原样回填）
+ */
+export declare function buildWecomSessionUpdateFrame(input: {
+    reqId: string;
+    /** 回调带回的原始 task_id（协议要求原样回填） */
+    cardTaskId: string;
+    sessionId: string;
+    lifecycle: WecomSessionUpdateLifecycle;
+    /** 会话标题（缺省用 sessionId 截断） */
+    title?: string;
+    agentType?: string;
+    /** 开始时间（ISO）；用于算「已运行」 */
+    startedAt?: string;
+    /** 已运行时长（优先用调用方算好的；缺省由 startedAt + now 推导） */
+    elapsedText?: string;
+    /** 关联 roy 任务（可选增强） */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /** 累积操作记录（最新在后；渲染时反转成最新在顶部） */
+    milestones?: WecomMilestoneLite[];
+    /**
+     * ★ Task #5419：该 session 已关联的**飞书群** chatId。
+     *
+     * 有 ⇒ horizontal 加一行「飞书群」（applink 跳转），
+     * 建群后按钮翻面语义由 handler 控制（幂等命中不重复建）。
+     */
+    perTaskChatId?: string;
+    /** ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title） */
+    errorHint?: string;
+    /** 活性快照。undefined = 不渲染；null = 暂无数据（用户点了必须有反馈） */
+    activity?: WecomActivityLike | null;
+    /** 时间基准（注入便于测试） */
+    now?: number;
 }): {
     cmd: string;
     headers: {

package/dist/env/event-source/wecom-cli-handler.d.ts

@@ -125,6 +125,13 @@ export interface WecomReplyChannelInput {
     sourceId?: string;
     /** ★ Task #5311：原始 req_id —— WS 被动回帧（带引用语义）需要 */
     reqId?: string;
+    /**
+     * ★ Task #5360（补充需求）：状态通知文本开关（来自 ES 配置）。
+     *
+     * 写进 `params` 让 delegate 快照带下去 —— 与 lark 侧同字段同语义。
+     * 严格 `=== true`；显式写 false（不省略，保留"源上显式关"的信息）。
+     */
+    statusNotifications?: boolean;
 }
 /**
  * 构造企微的 replyChannel。
@@ -182,6 +189,24 @@ export declare function buildWecomUserMessage(text: string, replyContext?: {
  * @param frame 原始帧（`aibot_msg_callback` / `aibot_event_callback`）
  */
 export declare function parseWecomFrame(raw: unknown): ParsedWecomFrame | null;
+/**
+ * 企微渠道**恒需**放行的 channel-only 工具。
+ *
+ * `wecom_respond` 是企微唯一出站通道（wecom-cli 主路径 + WS 回帧 fallback）。
+ * 它带有 `metadata.channelOnly = true`（Task #5333），默认对所有 agent 隐藏
+ * ——如果不在这里显式放行，企微事件的 agent 将**无法回复**用户。
+ */
+export declare const WECOM_DEFAULT_EXTEND_TOOLS: readonly string[];
+/**
+ * 解析企微渠道的 extendTools（默认 + 配置，去重保序）。
+ *
+ * 顺序：WECOM_DEFAULT_EXTEND_TOOLS 在前（确定性前缀），config.extendTools 在后。
+ * 去重保持首次出现位置 —— 保证同一 config 多次调用结果**逐字节一致**
+ * （对齐 buildWecomChannelSystemPrompt 的稳定性纪律，避免无意义的 diff）。
+ *
+ * @param config 事件源配置（可选字段 extendTools）
+ */
+export declare function resolveWecomExtendTools(config: EventSourceConfig | undefined): string[];
 /** 企微渠道 system prompt 的章节标题（lean 卡片指回这里） */
 export declare const WECOM_CHANNEL_PROMPT_SECTION_TITLE = "\u2B50 \u4F01\u4E1A\u5FAE\u4FE1\u56DE\u590D\u89C4\u8303\uFF08system prompt \u6CE8\u5165\u7248\uFF09";
 /** `buildWecomChannelSystemPrompt` 入参（只允许渠道级配置，禁 event） */

package/dist/{shared/@ai-setting/roy-agent-core-vyr6svt6.js → env/event-source/wecom-respond-registry.js}

@@ -10,12 +10,14 @@ import {
   unregisterWecomRespondTarget,
   wasWecomReplySent,
   wecomRespondTool
-} from "./roy-agent-core-m3vjepzz.js";
-import"./roy-agent-core-7cbpmk4q.js";
-import"./roy-agent-core-qq96p0tj.js";
-import"./roy-agent-core-7f7t9wwp.js";
-import"./roy-agent-core-85xyctnb.js";
-import"./roy-agent-core-fs0mn2jk.js";
+} from "../../shared/@ai-setting/roy-agent-core-h1e1fm9b.js";
+import"../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
+import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
+import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
+import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
   wecomRespondTool,
   wasWecomReplySent,