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

package/dist/env/task/plugins/card-subject.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Task #5360（用户澄清 2026-11-11 22:37）——
+ *   卡片实体：**sub-session 永远是主键**，task 是可选的**附加增强信息**
+ *
+ * ## 用户澄清原文（覆盖了此前「task-or-session 二选一」的理解）
+ *
+ * > 「**不是**「task 或 sub-session」二选一，而是**以 sub-session 为基底**：
+ * >  1. 卡片主键 = sub-session（不是 task）
+ * >  2. 有些 sub-session 内部创建了 task，有些没有 —— 都是正常的
+ * >  3. 如果该 sub-session 创建了 task → 把 task 信息同步进卡片
+ * >     （taskId、title、状态、进度、操作记录等原有信息一个不少）
+ * >  4. **无论有无 task，sub-session 相关的刷新逻辑始终存在**：
+ * >     刷新看消息数 + 最近 msg（截断）；
+ * >     **超时、完成等生命周期事件也体现在卡片上**（这是 subsession 层的）」
+ *
+ * ## 语义对比（这是本模块存在的全部理由）
+ *
+ * ```
+ * ❌ 旧（错）：type CardSubject = { kind:"task"; taskId } | { kind:"session"; sessionId }
+ *            → 主键二选一；task 卡和 session 卡是两张不同的卡
+ * ✅ 新（对）：type CardSubject = {
+ *              sessionId: string;        // ← 永远是主键，不可缺
+ *              taskId?: number;          // ← 可选增强，有就多显示
+ *            }
+ * ```
+ *
+ * 关键推论（写代码时最容易搞错的地方）：
+ *
+ * 1. **刷新永远读 session store**。有 task 时也读 session —— 因为
+ *    「消息数 + 最近 msg」是**会话**的属性，不是 task 的属性。
+ *    旧实现走 `taskId → bgTask → subSessionId → session`，绕了一圈才拿到
+ *    同一个 session；现在主键就是 sessionId，直达。
+ * 2. **生命周期（超时/完成/停止）是 session 层的事实**。旧设计里终态来自
+ *    `task.status`（没 task 就永远 non-terminal）—— 这正是本次要修的语义错误。
+ *    现在终态来自 **跑这个 session 的后台任务**（`BackgroundTask.status`），
+ *    与「该 session 有没有建 task」无关。
+ * 3. **有 task 只是"多一块信息"**，不改变卡片身份、不改变刷新行为。
+ *
+ * ## 序列化格式
+ *
+ * 持久层主键是字符串，格式：
+ *
+ * ```
+ * session:<sessionId>                    ← 无关联 task
+ * session:<sessionId>#task:<taskId>      ← 有关联 task（附加段）
+ * ```
+ *
+ * - 主键段**永远是 session**；`#task:` 段是纯附加值，缺了不影响解析
+ * - 用 `#` 分隔而不是再嵌 `:`，避免 session id 里含 `:` 时歧义
+ *   （session id 可能含 `-` / `_`，理论上也可能含别的；`#` 最少见）
+ * - 旧数据（只有 `task_id INTEGER`）迁移时**无法**反推 sessionId ⇒ 标记为
+ *   `legacy-task:<n>`，仅用于读旧卡（新卡不再产生这种形态）
+ */
+/**
+ * 卡片实体：**session 为主 + task 可选**。
+ *
+ * ⚠️ `sessionId` 必填 —— 这是本次澄清的核心，不要为了兼容旧代码把它变可选。
+ */
+export interface CardSubject {
+    /** ★ 主键：跑这次执行的 sub-session */
+    sessionId: string;
+    /** 附加增强：该 session 内创建的 roy 任务（可能没有） */
+    taskId?: number;
+}
+/** 持久层主键 */
+export type CardKey = string;
+/**
+ * 造卡片主键。**sessionId 必填**，taskId 可选（附加值）。
+ *
+ * @throws sessionId 为空（空主键会撞脏数据，宁可早失败）
+ */
+export declare function cardKeyOf(subject: CardSubject): CardKey;
+/** 便捷：只给 sessionId（无 task） */
+export declare function sessionCardKey(sessionId: string): CardKey;
+/** 便捷：sessionId + taskId */
+export declare function sessionTaskCardKey(sessionId: string, taskId: number): CardKey;
+/** 旧卡（迁移期只读）：`legacy-task:<n>` */
+export declare function legacyTaskCardKey(taskId: number): CardKey;
+/**
+ * 解析主键。
+ *
+ * 失败（非字符串 / 空 / 缺 `session:` 前缀 / sessionId 为空）一律
+ * `undefined` —— 调用方降级，**绝不抛、绝不猜**。
+ *
+ * 注意：`legacy-task:<n>` **不**解析成 CardSubject（它没有 sessionId，
+ * 无法参与刷新）；需要区分旧卡时用 `isLegacyTaskCardKey`。
+ */
+export declare function parseCardKey(key: unknown): CardSubject | undefined;
+/** 是否是迁移期的旧卡主键（只有 task、没有 session） */
+export declare function isLegacyTaskCardKey(key: unknown): boolean;
+/** 判定版 */
+export declare function isCardKey(v: unknown): v is CardKey;
+/**
+ * 从按钮 `value` 里挑出卡片实体。
+ *
+ * ## 与旧实现的关键差异
+ *
+ * 旧实现「taskId 优先，没有 taskId 才用 sessionId」—— 那会让**有 task 的
+ * session 卡**被当成 task 卡刷新（走 task→bgTask→session 绕路，且丢掉
+ * session 层的生命周期）。现在：**sessionId 是主键，taskId 只是附加值**，
+ * 所以 sessionId 必须存在，taskId 有就带上。
+ *
+ * @returns 无 sessionId ⇒ `undefined`（连主键都没有，无法刷新）
+ */
+export declare function pickCardSubject(value: {
+    sessionId?: unknown;
+    taskId?: unknown;
+}): CardSubject | undefined;
+/**
+ * 主标签：`会话 <sessionId 截断>`。
+ *
+ * session 是卡片身份，所以标签以它为主；task 信息在卡片正文里单独展示
+ * （见 `buildSessionCard` 的「任务信息」面板）。
+ */
+export declare function cardSubjectLabel(subject: CardSubject): string;
+/** 是否有关联 task（决定卡片是否渲染「任务信息」面板） */
+export declare function hasTask(subject: CardSubject): boolean;

package/dist/env/task/plugins/index.js

@@ -4,11 +4,9 @@ import {
   LarkCliTaskNotifyHook,
   LayaCompletionPlugin,
   LayaDecisionPlugin,
-  MemoryLarkCardStateStore,
   MemoryWecomCardStateStore,
   NotifyType,
   PerTaskGroupChatPlugin,
-  SqliteLarkCardStateStore,
   SqliteWecomCardStateStore,
   TaskTagPlugin,
   WORKFLOW_EXTRACTOR_PROMPT,
@@ -18,7 +16,6 @@ import {
   buildCompletionQuestion,
   buildWecomTaskCard,
   createAutoTaskPlugin,
-  createLarkCardStateStore,
   createLarkCliTaskNotifyHook,
   createLayaCompletionPlugin,
   createLayaDecisionPlugin,
@@ -29,18 +26,17 @@ import {
   extractWecomFields,
   formatExtractorInput,
   formatExtractorInputFromDescription,
-  getDefaultLarkCardDbPath,
   getDefaultWecomCardDbPath,
   parseExtractorOutput,
   registerLayaCompletionTaskHook,
   renderCompletionState
-} from "../../../shared/@ai-setting/roy-agent-core-b31v3qpv.js";
-import"../../../shared/@ai-setting/roy-agent-core-m3vjepzz.js";
-import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
-import"../../../shared/@ai-setting/roy-agent-core-ezvpreqz.js";
+} from "../../../shared/@ai-setting/roy-agent-core-k3h8t4q1.js";
+import"../../../shared/@ai-setting/roy-agent-core-h1e1fm9b.js";
+import"../../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../../shared/@ai-setting/roy-agent-core-4t3yskp8.js";
+import"../../../shared/@ai-setting/roy-agent-core-y7fqtzk2.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
+import"../../../shared/@ai-setting/roy-agent-core-d6zdbgtc.js";
 import"../../../shared/@ai-setting/roy-agent-core-m46fe3x4.js";
 import {
   TASK_COMPLETE_ACCEPTANCE,
@@ -51,12 +47,16 @@ import {
 import {
   DEFAULT_APP_LINK_BASE,
   LarkCardPatchNotifier,
+  MemoryLarkCardStateStore,
+  SqliteLarkCardStateStore,
   buildChatAppLink,
   buildTaskCard,
   buildWorkflowCard,
+  createLarkCardStateStore,
   formatDateTimeForDisplay,
   formatDurationMs,
   formatTimestampForDisplay,
+  getDefaultLarkCardDbPath,
   humanizeValue,
   renderContextAsLines,
   renderMilestones,
@@ -66,9 +66,11 @@ import {
   renderWorkflowInfoLines,
   resolveTaskTitleForDisplay,
   sanitizeInlineText
-} from "../../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
-import"../../../shared/@ai-setting/roy-agent-core-1v4g0d4x.js";
-import"../../../shared/@ai-setting/roy-agent-core-cgtq6427.js";
+} from "../../../shared/@ai-setting/roy-agent-core-0n1wwndq.js";
+import"../../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
+import"../../../shared/@ai-setting/roy-agent-core-m66ysky0.js";
+import"../../../shared/@ai-setting/roy-agent-core-rm7seqwb.js";
+import"../../../shared/@ai-setting/roy-agent-core-e08bvpaq.js";
 import"../../../shared/@ai-setting/roy-agent-core-er070zjq.js";
 import {
   TASK_OP_WATERMARK_AUDIT_INTERVAL,
@@ -76,12 +78,12 @@ import {
   TASK_OP_WATERMARK_MESSAGE_LIMIT,
   TaskOpWatermarkPlugin,
   createTaskOpWatermarkPlugin
-} from "../../../shared/@ai-setting/roy-agent-core-h21gngxf.js";
+} from "../../../shared/@ai-setting/roy-agent-core-7yh5wps0.js";
 import"../../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
 import"../../../shared/@ai-setting/roy-agent-core-az13yzmc.js";
-import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-tkpp1ba0.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";

package/dist/env/task/plugins/lark-card-action-handler.d.ts

@@ -14,12 +14,29 @@
  *   - 失败必须明确返回 ok=false，不静默成功
  */
 import { buildTaskCard, DEFAULT_APP_LINK_BASE, type LarkCardPatchNotifier } from "./lark-card-patch-notifier";
+import { type ActivityMessage, type ToolCallView, type ActivityProbeResult } from "./sub-session-activity";
 /** 卡片按钮点击事件的关键字段（精简版，caller 从 event 里挑出） */
 export interface CardActionEvent {
-    /** action.value 序列化成的对象 */
+    /**
+     * action.value 序列化成的对象
+     *
+     * ★ Task #5360：新增 `refresh_activity`（展示 sub-session 活性）
+     * ★ Task #5377（合并）：`action` 放宽成 string、`taskId` 放宽成可选 ——
+     *   这样未知 action 能走到 `Unknown action` 分支（而不是被 TS 挡掉后
+     *   运行时静默落到解散群分支），session 卡也能不带 taskId。
+     */
     actionValue: {
-        action: "create_group" | "disband_group";
-        taskId: string | number;
+        /** 运行时再校验（#5377：先判白名单）；合法值见 `CardActionName` */
+        action: CardActionName | string;
+        /** ★ Task #5360：task 卡带它；session 卡不带（可选，#5377） */
+        taskId?: string | number;
+        /**
+         * ★ 补充需求（22:31）：session 卡的主键。
+         *
+         * **它是卡片主键**（澄清 22:37）：刷新永远走 session store。
+         * `taskId` 只是附加增强 —— 有就多渲染「任务信息」面板，不影响刷新路径。
+         */
+        sessionId?: string;
     };
     /** 卡片所在的 chat_id */
     chatId: string;
@@ -38,6 +55,82 @@ export interface CardActionEvent {
     /** lark-cli profile */
     profile?: string;
 }
+/** 卡片动作名（★ Task #5360：加 `refresh_activity`） */
+export type CardActionName = "create_group" | "disband_group" | "refresh_activity";
+/**
+ * 运行时判定一个字符串是否是本 handler 认识的 action。
+ *
+ * ★ Task #5360（防误伤）：改造前 handler 的结构是
+ * ```ts
+ * if (action === "create_group") { ...建群... } else { ...解散群... }
+ * ```
+ * 也就是**任何**非 create_group 的 action 都会走解散群分支。
+ * 加了 `refresh_activity` 之后，如果只在新分支外面套一层判断，漏掉/拼错
+ * 的 action（或未来第三方卡片复用同一 handler）会**默默解散用户的群**。
+ * 所以改成显式白名单 + switch，未知 action 一律 `ok:false` 且**不执行任何操作**。
+ */
+export declare function isCardActionName(v: unknown): v is CardActionName;
+/** ★ Task #5377：actionValue 的运行时形状（字段都可能缺，先当 unknown 校验） */
+export interface CardActionValue {
+    action?: unknown;
+    taskId?: unknown;
+    sessionId?: unknown;
+}
+/** ★ Task #5377：校验结果（判别联合 —— 通过时主键已收窄成对应类型） */
+export type CardActionValidation = {
+    ok: true;
+    action: "create_group" | "disband_group";
+    taskId: number;
+    sessionId?: string;
+} | {
+    ok: true;
+    action: "create_group" | "disband_group";
+    taskId?: undefined;
+    sessionId: string;
+} | {
+    ok: true;
+    action: "refresh_activity";
+    sessionId: string;
+} | {
+    ok: false;
+    action: string;
+    error: string;
+};
+/**
+ * ★ Task #5377 修复主体：**先判 action 白名单，再按 action 类型取主键**。
+ *
+ * 顺序契约（不可颠倒）：
+ *   1. action 不在白名单 → `Unknown action: <action>`
+ *      （此时**不看** taskId/sessionId —— 未知动作不该报"缺字段"，
+ *      更不能落到解散群分支误删用户的群）
+ *   2. 白名单内 → 按 `ACTION_SUBJECT_FIELD` 只校验该 action 需要的那一个字段
+ *   3. 缺 / 非法 → 错误信息**必须指明字段名**（taskId 或 sessionId）
+ *
+ * 纯函数、无 IO，便于逐个 action 单测。
+ */
+export declare function validateCardActionValue(raw: CardActionValue): CardActionValidation;
+/**
+ * ★ Task #5377：session 类卡片（refresh_activity）的外部刷新实现（**可选**）。
+ *
+ * 生产默认**不需要**注入它 —— 内置的 `handleRefreshSessionActivity`（#5364）
+ * 只依赖数据端口 `loadSessionActivity` 就能渲染整张 session 卡。
+ * 本端口留给需要跨进程 / 特殊渲染的宿主复用同一 handler。
+ *
+ * ⚠️ 契约：**端口只负责 render，不负责发**。返回的 `cardUpdate` 由 caller
+ * 统一 patch（见 event-source-handlers 的 handleCardActionEvent），
+ * 所以端口实现**不要**自己再 patch 一次（会重复更新）。
+ */
+export type SessionCardRefreshHandler = (opts: {
+    sessionId: string;
+    chatId: string;
+    messageId: string;
+    token: string;
+    profile?: string;
+}) => Promise<{
+    /** 渲染好的卡片 payload（caller 负责发） */
+    cardUpdate?: ReturnType<typeof buildTaskCard>;
+    error?: string;
+}>;
 /** 端口注入（caller 提供 IO 能力，本模块保持纯函数） */
 export interface CardActionPorts {
     /** 读取 task（用于读 context） */
@@ -58,12 +151,14 @@ export interface CardActionPorts {
     /**
      * 创建群聊
      * @param opts.initialUserIds ★ Task #4337：建群时一并拉人（如操作者 open_id）；用 `+chat-create --users` 一次到位
+     * @param opts.initialBotIds ★ Task #5425：建群时一并拉 bot（app_id cli_xxx）；不拉 bot 发卡会 230002
      */
     createGroupChat?: (opts: {
         name: string;
         description: string;
         profile?: string;
         initialUserIds?: string[];
+        initialBotIds?: string[];
     }) => Promise<string>;
     /** 解散群聊 */
     deleteGroupChat?: (chatId: string, profile?: string) => Promise<void>;
@@ -73,7 +168,128 @@ export interface CardActionPorts {
      * （caller 实现可以是 no-op，因为 --users 已经邀请好了）
      */
     inviteUser?: (chatId: string, userOpenId: string, profile?: string) => Promise<void>;
-    /** 卡片更新（用 messageId patch） */
+    /**
+     * ★ Task #5360：读 sub-session 活性（消息数 + 最后写入时间 + 最近消息）。
+     *
+     * 用户点「🔄 刷新活性」时调用，用来判断**有没有 LLM 在推进**。
+     *
+     * 不注入 / 抛错 / 返回 undefined ⇒ 卡片渲染「暂无数据」，
+     * **绝不让 patch 失败**（与其它端口同一套 best-effort 语义）。
+     *
+     * 装配点见 `event-source-handlers.ts` 的 `wireCardActionPorts()`
+     * （复用 `createActivityProbe`，与企微侧同一份实现）。
+     */
+    loadSubSessionActivity?: (taskId: number) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ Task #5360：任务是否已终态（决定活性档位报「已结束」而非「疑似停滞」）。
+     * 不注入 ⇒ 按非终态处理（最坏情况是终态任务显示"疑似停滞"，不影响可用性）。
+     */
+    isTerminalTask?: (taskId: number) => Promise<boolean> | boolean;
+    /**
+     * ★ CV BLOCKER-1：按 taskId 反查所属 sub-session（旧卡片向后兼容）。
+     *
+     * 存量 task 卡的按钮 value 只有 `taskId`（改造前的形态）。为了让它们
+     * 不失效，用一个反查端口把它们补成标准 `{sessionId, taskId}` subject。
+     *
+     * 装配点实现：`taskId → BackgroundTaskManager.listTasks() 里
+     * associatedTaskId 命中 → subSessionId`。
+     * 不注入 / 反查不到 ⇒ 旧卡片刷新被拒（不猜）。
+     */
+    resolveSessionIdByTask?: (taskId: number) => Promise<string | undefined> | string | undefined;
+    /**
+     * ★ 补充需求（22:31）：**session-only** 活性读取（无 task 场景）。
+     *
+     * 与 `loadSubSessionActivity(taskId)` 的区别：后者要从 task 反查 bgTask 才能
+     * 拿到 subSessionId；本端口**直达** session store —— 因为调用方手里已经有
+     * sessionId 了，而这条链上**根本没有 task**。
+     *
+     * 不注入 / 抛错 ⇒ 卡片渲染「暂无数据」，绝不阻断 patch。
+     */
+    loadSessionActivity?: (sessionId: string) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ Task #5420：「💬 会话查看」—— 读最近 N 条消息。
+     *
+     * 与 `loadSessionActivity` 的区别：活性只带**最近 1 条**消息
+     * （判断有无 LLM 推进够用）；本端口取**尾部 5 条**（用户拍板
+     * 「A 五条，只展示名称和 reason」）。
+     *
+     * 装配点实现：`getMessages(sessionId, { offset: -1, limit: 5 })`
+     * （sqlite 负 offset 语义 = total + offset*limit，-1×5 = 最新 5 条）。
+     *
+     * 不注入 / 抛错 / 返回 undefined ⇒ **不渲染**最近消息面板
+     * （降级不抛，与活性端口同一套 best-effort 语义）；
+     * 返回 [] ⇒ 面板照出 + 「暂无消息」（诚实）。
+     */
+    loadSessionMessages?: (sessionId: string, limit?: number) => Promise<ActivityMessage[] | ToolCallView[] | undefined> | ActivityMessage[] | ToolCallView[] | undefined;
+    /**
+     * ★ Task #5403：建群成功后初始化「群 session」—— **关联建群**。
+     *
+     * 取代 #5369 的 `linkSessionAlias`（alias / linkedTo 能力已整体废弃）。
+     *
+     * 新语义：群 session 是**独立会话**，不共享原会话历史。本端口负责：
+     *  1. 建/补群 session 行（id = chatId，metadata 带 `linkedFromSessionId`）
+     *  2. 注入 **1 条 user role** 事件说明「本群由 session X 关联建群，需要
+     *     背景时用 `roy-agent sessions messages X` 按需读取」
+     *
+     * 为什么不共享历史（用户 2026-11-12 定稿）：群 session 由 default agent 的
+     * system prompt 驱动，原 sub session 由 sub agent 驱动 —— 复用 history 会让
+     * LLM prefix cache 失效，且 sub agent 的 delegate prompt（「不要发飞书消息」）
+     * 会污染群对话（#5396 实测 0 回复）。
+     *
+     * 可选端口：
+     *  - 未注入 → 建群照旧成功（向后兼容，老部署不炸）
+     *  - 抛错   → best-effort 吞掉，**绝不回滚已建好的群**
+     */
+    attachGroupSession?: (args: {
+        chatId: string;
+        originSessionId: string;
+        title?: string;
+    }) => Promise<unknown>;
+    /**
+     * ★ Task #5397：**会话 → 群** 反向查询（等价 task 维度的
+     * `task.context.larkPerTaskChatId`）。
+     *
+     * 用途（三处）：
+     * 1. **重复建群保护**：同 session 已有群 ⇒ 返回已有群链接，不新建
+     * 2. 卡片显示已有群链接（session 卡首渲 / 刷新时带 `perTaskChatId`）
+     * 3. 解绑时定位要解散哪个群
+     *
+     * 装配点实现：`SessionComponent.findGroupChatForSession(sessionId)`
+     * —— 扫 metadata `linkedFromSessionId`（Task #5403 起，走 JSON1 抽取，
+     * 零 schema 变更；`linked_to` 列已废弃不再使用）。
+     *
+     * 不注入 ⇒ session-only 建群失去重复保护（仍能建），解绑退化为「无群可解」
+     * （明确报错，不静默成功）。
+     */
+    findGroupChatForSession?: (sessionId: string) => Promise<{
+        chatId: string;
+        aliasSessionId?: string;
+    } | undefined> | {
+        chatId: string;
+        aliasSessionId?: string;
+    } | undefined;
+    /**
+     * ★ Task #5403：解除「会话 ↔ 群」的关联（解绑时调用）。
+     *
+     * 取代 #5397 的 `unlinkSessionAlias`。新语义：群 session 是独立会话，解绑
+     * 只是把「这个群还活着」的标记打掉（metadata.groupDisbandedAt），让
+     * `findGroupChatForSession` 不再命中它。
+     *
+     * 不注入 / 抛错 ⇒ best-effort 吞掉（群已经解散了，不能让 detach 失败把结果
+     * 翻成失败）。
+     */
+    detachGroupSession?: (chatId: string) => Promise<{
+        ok: boolean;
+    } | void>;
+    /**
+     * ★ Task #5397：读会话标题（session-only 建群时用来生成群名）。
+     *
+     * 不注入 / 取不到 ⇒ 群名退化为 `会话 <sessionId 截断>`。
+     */
+    getSessionTitle?: (sessionId: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * 卡片更新（用 messageId patch）
+     */
     notifier: LarkCardPatchNotifier;
     /**
      * ★ Task #4339：用飞书 30min token patch 卡片（可选端口）。
@@ -86,12 +302,24 @@ export interface CardActionPorts {
      * 抽成端口是为了单测能断言"patch 被调用了 / 内容对不对"而不真发请求。
      */
     patchByToken?: (token: string, card: unknown, profile?: string) => Promise<void>;
+    /**
+     * ★ Task #5377：session 类卡片（refresh_activity）的外部刷新实现（可选）。
+     *
+     * 未注入 ⇒ 走内置 `handleRefreshSessionActivity`（#5364 生产默认路径）；
+     * 连 `loadSessionActivity` 也没有 ⇒ 返回**指明 action 的**错误
+     * （而不是改造前那句误导性的 `Invalid taskId: undefined`）。
+     */
+    refreshSessionCard?: SessionCardRefreshHandler;
 }
 /** 路由决策 / 处理结果 */
 export interface CardActionResult {
     ok: boolean;
-    /** 成功执行的操作 */
-    action: "create_group" | "disband_group";
+    /**
+     * 成功执行的操作。
+     * ★ 合并：`CardActionName`（正常路径）× `#5377` 未知 action 时保留原始字符串
+     * （便于日志定位是哪个拼错/第三方动作打进来的）
+     */
+    action: CardActionName | string;
     /** 新的 chatId（create 成功时返回；disband 成功时返回空） */
     newChatId?: string;
     /** 给飞书的卡片更新 payload（用 token 即时 patch） */
@@ -109,6 +337,13 @@ export declare function __resetCardActionInflightForTest(): void;
  * @returns 处理结果（ok=true 表示 action 已成功执行；ok=false 表示错误）
  */
 export declare function handleCardAction(event: CardActionEvent, ports: CardActionPorts): Promise<CardActionResult>;
+/**
+ * task.status → **session 生命周期**映射。
+ *
+ * ⚠️ 这不是「task 状态」——它表示「跑这个 session 的执行是否已结束」。
+ * 只映射到生命周期允许的 5 个值；未知状态保守当 `running`。
+ */
+export declare function lifecycleOfTaskStatus(status: string | undefined): "running" | "completed" | "timeout" | "failed" | "stopped" | undefined;
 /**
  * "解散"群聊（Task #4331 实测发现：飞书 Open API **不支持解散群聊**）
  *
@@ -142,6 +377,17 @@ export declare function deleteGroupChatViaLarkCli(chatId: string, profile?: stri
  *   引号 / `$` / 反引号 / `;` 破坏（命令截断甚至注入）。
  */
 export declare function shellQuote(s: string): string;
+/**
+ * ★ Task #5425：解析当前 profile 对应的 bot app_id（cli_xxx）。
+ *
+ * 用 `lark-cli <profile> auth status --json` 的 `appId` 字段
+ * （与 deleteGroupChatViaLarkCli 同款解析）。建群时把它传给
+ * `+chat-create --bots`，让创建者 bot 进群 —— 否则 bot 发卡
+ * （#5417 新群 session 卡）会报 230002。
+ *
+ * @throws lark-cli 失败 / 输出无 appId 时抛错（caller best-effort）
+ */
+export declare function resolveBotAppId(profile?: string): Promise<string>;
 /**
  * 截断到指定长度（含 "..."，语义与 PerTaskGroupChatPlugin.truncate 一致）
  *
@@ -161,6 +407,15 @@ export declare function createGroupChatViaLarkCli(opts: {
     profile?: string;
     /** ★ Task #4339：建群时一并拉人（lark-cli `+chat-create --users "ou_a,ou_b"`） */
     initialUserIds?: string[];
+    /**
+     * ★ Task #5425：建群时一并拉 bot（lark-cli `+chat-create --bots "cli_xxx"`）。
+     *
+     * 背景：`--as bot` 创建群时**创建者 bot 默认不在群里**（飞书行为），
+     * 后续 `+messages-send`（发 session 卡）会报
+     * 230002「Bot/User can NOT be out of the chat」→ 新群永远没卡。
+     * 传本群要用的 bot app_id（cli_xxx）即可在建群时拉 bot 入群。
+     */
+    initialBotIds?: string[];
 }): Promise<string>;
 /** 重新导出 DEFAULT_APP_LINK_BASE 方便测试用 */
 export { DEFAULT_APP_LINK_BASE };