@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/task/plugins/fake-user-message-helper.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Shared meta-protocol helper for `toolResult.result.metadata.toAddFakeUserMessage`
+ *
+ * Task #2580 (round 2) — Extracted shared helper for the meta-protocol
+ * used by `agent:after.tool` plugins. Both `AutoTaskPlugin` (delegate hint)
+ * and `MaxIterationReminderPlugin` (max-iteration final reminder) write
+ * to the same `toolResult.result.metadata.toAddFakeUserMessage` field.
+ *
+ * ## Why a shared helper
+ *
+ * When both plugins fire on the same iteration (e.g., `threshold === maxIter-1`),
+ * they would both write to the same metadata field. The second write would
+ * silently overwrite the first, losing one of the reminders.
+ *
+ * The shared helper provides **deterministic merge**:
+ * - Tracks each message's `kind` ("delegate" vs "max-iter")
+ * - Merges so the final message order is: `[delegate..., max-iter...]`
+ *   (max-iter is always the "last word" / final instruction)
+ * - Both reminders are preserved (no silent overwrite)
+ *
+ * ## Why this is NOT a side-channel
+ *
+ * - Uses the EXISTING `toolResult.result.metadata.toAddFakeUserMessage` field
+ * - No new fields on `HookContext` or `AgentContext`
+ * - No new AgentComponent helper
+ * - The `__fakeUserMessageKind` side field is a small internal marker that
+ *   AgentComponent's `consumeMetaProtocolUserMessage` does NOT read or
+ *   delete — it only reads `toAddFakeUserMessage` and deletes that.
+ * - Both plugins and AgentComponent keep using the same meta-protocol path
+ *   introduced by Task #2170.
+ *
+ * ## Observability (Task #2580 round 3)
+ *
+ * The helper is wrapped with `wrapFunction` to expose a stable span name
+ * `plugin.fake-user-message.enqueue` (see `enqueueToAddFakeUserMessage`
+ * export below). The span's `attributes` capture:
+ *   - `kind` ("delegate" or "max-iter")
+ *   - `will-merge` (true if existing metadata was present)
+ *   - `merged-final-kind` (the kind of the final merged message)
+ *
+ * This is the primary evidence point for verifying in trace that a plugin
+ * actually wrote the meta-protocol field at iter=9 (maxIter-1).
+ */
+import type { ModelMessage } from "ai";
+/**
+ * Kinds of fake user messages. Used for deterministic merge ordering.
+ *
+ * Priority: "max-iter" > "delegate"
+ * - "max-iter" reminders contain "不要再调用任何工具，直接总结" (final instruction)
+ * - "delegate" reminders contain "use delegate_task" (earlier hint)
+ *
+ * The final merged message always ends with the max-iter reminder.
+ */
+export type FakeUserMessageKind = "delegate" | "max-iter";
+/**
+ * Internal implementation of the enqueue helper. Not exported directly;
+ * instead `enqueueToAddFakeUserMessage` (the wrapped version) is exported
+ * so that every call goes through the trace span.
+ *
+ * @internal
+ */
+declare function enqueueToAddFakeUserMessageImpl(toolResult: any, newMsg: ModelMessage, newKind: FakeUserMessageKind): {
+    willMerge: boolean;
+    finalKind: FakeUserMessageKind;
+};
+/**
+ * Enqueue a fake user message via the meta-protocol field
+ * `toolResult.result.metadata.toAddFakeUserMessage`.
+ *
+ * If the field is empty, sets it. If the field is already set (by another
+ * plugin firing in the same `agent:after.tool` invocation), merges the new
+ * message with the existing one deterministically:
+ *   - "max-iter" messages always go AFTER (final instruction at the end)
+ *   - "delegate" messages go BEFORE if existing was max-iter; otherwise
+ *     normal "newer wins" by appending (rare; two delegates on same iter)
+ *
+ * Both reminders are preserved — no silent overwrite.
+ *
+ * The original kind marker is stored in `__fakeUserMessageKind` (hidden
+ * metadata field) and is NOT read by AgentComponent's
+ * `consumeMetaProtocolUserMessage`. AgentComponent only reads
+ * `toAddFakeUserMessage` and deletes it; other metadata fields are
+ * untouched.
+ *
+ * @param toolResult - `ctx.toolResult` (mutated in-place)
+ * @param newMsg - The new fake user message
+ * @param newKind - Kind of the new message (determines merge order)
+ */
+export declare const enqueueToAddFakeUserMessage: typeof enqueueToAddFakeUserMessageImpl;
+export {};

package/dist/env/task/plugins/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Task Plugins Module
+ */
+export { TaskTagPlugin } from "./task-tag-plugin";
+export { createAutoTaskPlugin, type AutoTaskPluginConfig, } from "./auto-task-plugin";
+export { WORKFLOW_EXTRACTOR_PROMPT, formatExtractorInput, formatExtractorInputFromDescription, parseExtractorOutput, } from "./workflow-extractor-agent";
+export { LarkCliTaskNotifyHook, createLarkCliTaskNotifyHook, type TaskNotifyConfig, NotifyType, } from "./lark-cli-task-notify-plugin";
+export { PerTaskGroupChatPlugin, createPerTaskGroupChatPlugin, type PerTaskGroupConfig, } from "./per-task-group-chat-plugin";

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

@@ -10,12 +10,12 @@ import {
   formatExtractorInput,
   formatExtractorInputFromDescription,
   parseExtractorOutput
-} from "../../../shared/@ai-setting/roy-agent-core-pkpkctvf.js";
+} from "../../../shared/@ai-setting/roy-agent-core-g36jevrk.js";
 import"../../../shared/@ai-setting/roy-agent-core-yhsssn86.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../../shared/@ai-setting/roy-agent-core-gdsqp6j8.js";
-import"../../../shared/@ai-setting/roy-agent-core-j8e92gj8.js";
-import"../../../shared/@ai-setting/roy-agent-core-na73mym1.js";
+import"../../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../../shared/@ai-setting/roy-agent-core-b5ew8t0k.js";
+import"../../../shared/@ai-setting/roy-agent-core-a4vzsn0g.js";
 import"../../../shared/@ai-setting/roy-agent-core-8s9jd2qy.js";
 import"../../../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
 import"../../../shared/@ai-setting/roy-agent-core-dv714bqh.js";

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

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview 处理飞书卡片按钮点击（Task #4331）
+ *
+ * 用户在卡片顶部点 button：
+ *   - "为这个任务建群" → ensureGroupChat + 写 task.context.larkPerTaskChatId
+ *   - "解散该群" → lark-cli im +chat-delete + 清 task.context.larkPerTaskChatId
+ *   - 两种 case 都触发卡片 patch（按钮翻转 + 链接显示/隐藏）
+ *
+ * 触发源：lark-cli event consume card.action.trigger（参看 lark-card-action-handler.test.ts）
+ *
+ * 设计原则：
+ *   - 纯函数 + IO 端口注入（taskGetter / taskUpdater / notifier / chatCreator / chatDeleter）
+ *   - 不依赖具体 bot 身份 / profile（由 caller 注入）
+ *   - 失败必须明确返回 ok=false，不静默成功
+ */
+import { buildTaskCard, DEFAULT_APP_LINK_BASE, type LarkCardPatchNotifier } from "./lark-card-patch-notifier";
+/** 卡片按钮点击事件的关键字段（精简版，caller 从 event 里挑出） */
+export interface CardActionEvent {
+    /** action.value 序列化成的对象 */
+    actionValue: {
+        action: "create_group" | "disband_group";
+        taskId: string | number;
+    };
+    /** 卡片所在的 chat_id */
+    chatId: string;
+    /** 被点的卡片 message_id（用于 notifier.updateTask） */
+    messageId: string;
+    /** 飞书提供的 token（30min 有效，可直接更新卡片） */
+    token: string;
+    /**
+     * 触发用户 open_id（Task #4337 用于拉人进群）
+     * 兼容 string 或 {open_id: "ou_xxx"} 两种格式
+     * （lark-cli event consume 的 card.action.trigger 字段是对象形式）
+     */
+    operatorId?: string | {
+        open_id: string;
+    };
+    /** lark-cli profile */
+    profile?: string;
+}
+/** 端口注入（caller 提供 IO 能力，本模块保持纯函数） */
+export interface CardActionPorts {
+    /** 读取 task（用于读 context） */
+    getTask?: (id: number) => Promise<{
+        context?: string;
+        title?: string;
+        description?: string;
+        goals?: string;
+        priority?: string;
+        type?: string;
+        project_path?: string;
+        parent_task_id?: number | null;
+        current_status?: string;
+        id: number;
+    } | undefined>;
+    /** 写 task.context（用于回写/清除 larkPerTaskChatId） */
+    updateTaskContext?: (taskId: number, newContext: string) => Promise<void>;
+    /**
+     * 创建群聊
+     * @param opts.initialUserIds ★ Task #4337：建群时一并拉人（如操作者 open_id）；用 `+chat-create --users` 一次到位
+     */
+    createGroupChat?: (opts: {
+        name: string;
+        description: string;
+        profile?: string;
+        initialUserIds?: string[];
+    }) => Promise<string>;
+    /** 解散群聊 */
+    deleteGroupChat?: (chatId: string, profile?: string) => Promise<void>;
+    /**
+     * 拉用户进群（Task #4337 后置邀请 fallback）
+     * 实际推荐用 createGroupChat({initialUserIds}) 一次到位；本端口是 fallback
+     * （caller 实现可以是 no-op，因为 --users 已经邀请好了）
+     */
+    inviteUser?: (chatId: string, userOpenId: string, profile?: string) => Promise<void>;
+    /** 卡片更新（用 messageId patch） */
+    notifier: LarkCardPatchNotifier;
+    /**
+     * ★ Task #4339：用飞书 30min token patch 卡片（可选端口）。
+     *
+     * 飞书推 card.action.trigger 时会带一个 30min 有效、最多用 2 次的 token；
+     * 点了按钮之后必须立刻用它把原卡片刷成新形态（按钮翻面 + 群链接）。
+     *
+     * 不注入时 caller 用默认实现（`patchCardByLarkCli` → `lark-cli api POST
+     * /open-apis/interactive/v1/card/update`）。
+     * 抽成端口是为了单测能断言"patch 被调用了 / 内容对不对"而不真发请求。
+     */
+    patchByToken?: (token: string, card: unknown, profile?: string) => Promise<void>;
+}
+/** 路由决策 / 处理结果 */
+export interface CardActionResult {
+    ok: boolean;
+    /** 成功执行的操作 */
+    action: "create_group" | "disband_group";
+    /** 新的 chatId（create 成功时返回；disband 成功时返回空） */
+    newChatId?: string;
+    /** 给飞书的卡片更新 payload（用 token 即时 patch） */
+    cardUpdate?: ReturnType<typeof buildTaskCard>;
+    /** 错误信息（ok=false 时） */
+    error?: string;
+}
+/**
+ * 测试钩子：清空 in-flight 去重表（仅供单测 beforeEach 使用）。
+ */
+export declare function __resetCardActionInflightForTest(): void;
+/**
+ * 处理卡片按钮点击
+ *
+ * @returns 处理结果（ok=true 表示 action 已成功执行；ok=false 表示错误）
+ */
+export declare function handleCardAction(event: CardActionEvent, ports: CardActionPorts): Promise<CardActionResult>;
+/**
+ * "解散"群聊（Task #4331 实测发现：飞书 Open API **不支持解散群聊**）
+ *
+ * 实测结论（2026-10-18 / 2026-10-19 复核）：
+ * - 飞书开放平台 lark-cli skill 文档：chats 只有 `create / get / link / update`，**没有 dissolve / delete**
+ * - 开放 API `DELETE /open-apis/im/v1/chats/:id` 也不存在
+ * - ★ Task #4339 复核：**旧实现用的 `/chats/:id/members/me` 是 404 不存在的路径**
+ *   （实测 `HTTP 404: 404 page not found`），所以历史上"bot 退群"从未真正执行过，
+ *   只是被 `2>/dev/null` 吞掉 + `echo 完成` 伪装成成功。
+ *
+ * 真实可用的退群接口（已用无效 chat_id 探活确认路径存在，返回 99992356 而非 404）：
+ *   DELETE /open-apis/im/v1/chats/:chat_id/members?member_id_type=app_id
+ *   body: {"id_list": ["<bot 的 app_id>"]}
+ *
+ * 用户原意"解散该群" → 我们做的是**逻辑解散**：
+ * 1. 调 deleteGroupChat 让 bot 退群（能退就退）
+ * 2. 把 chat_id 从 task.context 移除（后续不再往这个群发卡片）
+ * 3. 重新渲染卡片（按钮翻回"建群" + 隐藏链接）
+ * 4. 飞书侧的群仍存在（用户后续可手动删除 / 保留作为历史）
+ *
+ * ⚠️ 已知限制：群是 bot 自己建的 → bot 可能是群主；飞书对"群主退群"有额外约束，
+ *    这种情况下退群会失败。失败不阻断主流程（context 仍会清掉），但会打 warn。
+ *
+ * @returns 无（失败也 resolve，由日志体现）
+ */
+export declare function deleteGroupChatViaLarkCli(chatId: string, profile?: string): Promise<void>;
+/**
+ * shell 安全引用（单引号包裹 + 内部单引号转义）
+ *
+ * ★ Task #4339：task 标题是任意用户文本，直接 `"${name}"` 插值会被
+ *   引号 / `$` / 反引号 / `;` 破坏（命令截断甚至注入）。
+ */
+export declare function shellQuote(s: string): string;
+/**
+ * 截断到指定长度（含 "..."，语义与 PerTaskGroupChatPlugin.truncate 一致）
+ *
+ * ★ Task #4339：lark-cli `+chat-create` 的硬限制是
+ *   `--name` ≤ 60 字符 / `--description` ≤ 100 字符，超了直接报错 →
+ *   任务标题一长，"建群"按钮就彻底不可用。
+ */
+export declare function truncateText(text: string, maxLen: number): string;
+/**
+ * 调 lark-cli im +chat-create 建群（供 ports.createGroupChat 使用）
+ *
+ * 返回新建的 chatId。
+ */
+export declare function createGroupChatViaLarkCli(opts: {
+    name: string;
+    description: string;
+    profile?: string;
+    /** ★ Task #4339：建群时一并拉人（lark-cli `+chat-create --users "ou_a,ou_b"`） */
+    initialUserIds?: string[];
+}): Promise<string>;
+/** 重新导出 DEFAULT_APP_LINK_BASE 方便测试用 */
+export { DEFAULT_APP_LINK_BASE };