eve-lark 0.3.0 → 0.3.2

package/README.zh-CN.md

@@ -2,48 +2,48 @@
 
 [English](./README.md) | 简体中文
 
-一个为 [eve](https://eve.dev) agent 框架打造的 [Lark](https://www.larksuite.com) / [Feishu](https://www.feishu.cn) 通道。把工厂函数放到 `agent/channels/lark.ts`，eve 就会挂载一个 Lark webhook，把收到的私聊消息和群组 @ 提及转换成流式交互卡片回复。
+一个为 [eve](https://eve.dev) agent 框架打造的 [Lark](https://www.larksuite.com) / [Feishu](https://www.feishu.cn) 通道。把工厂函数放到 `agent/channels/lark.ts`，eve 就会挂载一个 Lark webhook，把收到的私聊消息和群组 @ 提及转成回复。
 
 ## 特性
 
 **入站**
-- 文本、富文本（`post`）、`@` 提及（包括 `@all`）
-- 图片和文件附件（服务端下载并暂存给模型使用）
-- 通过 `root_id` / `parent_id` 实现的话题回复
-- `event_id` 去重（处理 Feishu 的 at-least-once 重试）
+- 文本、富文本（`post`）、`@`-提及（包括 `@all`）
+- 图片和文件附件（服务端下载并 stage 给模型）
+- 通过 `root_id` / `parent_id` 跟踪线程
+- `event_id` 去重（应对飞书 at-least-once 重试）
 
 **出站**
-- 流式交互卡片（在对话过程中实时 patch 更新）—— 默认模式
-- 静态一次性卡片回复 —— 可配置
-- 话题回复保留原始 `root_id`
+- 流式交互卡片（对话过程中实时 patch）—— 可选模式
+- `post` 富文本消息（**默认**，渲染为原生聊天消息大小，支持 markdown）
+- 静态一次性卡片 —— 可选
+- 线程回复保留原始 `root_id`
 
 **安全**
-- `X-Lark-Signature` 签名校验（`sha256(timestamp + nonce + encrypt_key + body)`，恒定时间比较）
-- 当配置了 `encryptKey` 时，对 `encrypt` 信封进行 AES-256-CBC 解密
-- 时间戳偏移窗口（默认 5 分钟）
-- 抑制 bot 自身发出的消息
+- `X-Lark-Signature` 校验（`sha256(timestamp + nonce + encrypt_key + body)`，constant-time）
+- 当配置了 `encryptKey` 时，AES-256-CBC 解密 `encrypt` 信封
+- 时间戳偏差窗口（默认 5 分钟）
+- 抑制 bot 自己发的消息
 
-**Feishu 和 Lark 都支持**，只需切换一个 `baseUrl` 即可。
+**交互式 ask_question**——当模型调用 eve 内置的 `ask_question` 工具时，eve-lark 会把提示渲染成一张飞书交互卡片，每个选项对应一个按钮（option.style `primary` / `default` / `danger` 直接映射到飞书 button type）。用户点击触发 `card.action.trigger` 回调，channel 把答案作为 `InputResponse` 发回 eve，parked session 恢复。`allowFreeform: true` 允许用户直接回复普通聊天消息代替点击——下一条同 chat 内的消息会被拦截为答案。回答后卡片原地更新（移除按钮，选中项以绿色 ✓ 标记）。
 
-### v1 暂不支持
+**Feishu（飞书）和 Lark（国际版）** 通过单一的 `baseUrl` 切换支持。
 
-以下能力**有意**没有发布 —— 如果需要请提 issue：
-- 入站的音频 / 媒体 / 贴纸 / share_chat / share_user（仅 ack 并跳过）
+### 不在 v1 范围内
+
+以下功能**未实现**——需要的话请提 issue：
+- 音频 / 媒体 / sticker / share_chat / share_user 入站（仅 ack-and-skip）
 - 多账号配置
-- 用户级 OAuth（`user_access_token` 设备流程）
-- Feishu API 工具（文档 / 多维表格 / 日历 / 任务 / 云盘）
-- 卡片动作按钮（不支持交互式表单）
+- 用户级 OAuth（`user_access_token` device flow）
+- 飞书 API 工具（docs / bitable / calendar / tasks / drive）
 
-## 快速开始
+> `ask_question` 的卡片按钮**已实现**（0.3.0+）。下面列表中剩下的「Card action buttons」指的是 agent 自己生成的完全自定义的卡片 schema。
+- Card action buttons（agent 自定义的交互表单）
 
-安装：
+## 快速开始
 
-```bash
-pnpm add eve-lark
-# 或者：npm install eve-lark / yarn add eve-lark
-```
+两步。一个文件，一条命令。
 
-在你的 eve agent 中创建通道：
+**1. 声明 channel：**
 
 ```ts
 // agent/channels/lark.ts
@@ -58,19 +58,29 @@ export default createLarkChannel({
 });
 ```
 
-然后在 [Feishu 开发者后台](https://open.feishu.cn/app)（或 [Lark 开发者后台](https://open.larksuite.com/app)）中：
+**2. 跑 `eve dev`：**
 
-1. 创建一个**自建应用**，记录 `App ID` 和 `App Secret`。
-2. 在**事件订阅**中，把请求 URL 设置为你的 agent 的 `/lark/webhook`（可通过 `webhookPath` 选项覆盖）。
-3. 生成 **Verification Token** 和 **Encrypt Key** —— 都复制到你的环境变量里。
-4. 订阅 `im.message.receive_v1` 事件。
-5. 把 bot 拉进群组或直接私聊。
+```bash
+pnpm add eve-lark eve
+eve dev
+```
+
+完事。channel 在构造时副作用启动一个飞书 `WSClient`——飞书只看到这条出站 WebSocket，**本地开发不需要公网 webhook URL**。每个事件被重新签名 + 重新加密，POST 到 channel 自己在 `localhost` 的 webhook，由标准 handler 处理（完整 `send()` 访问权限）。
+
+在 [飞书开发者后台](https://open.feishu.cn/app)：
+1. 创建**自建应用**。记下 `App ID` 和 `App Secret`。
+2. 进入**事件订阅**，选择**「使用长连接接收事件」**模式（不是 HTTP 回调）。
+3. 生成**Verification Token** 和**Encrypt Key**——都填进你的 env。
+4. 订阅 `im.message.receive_v1`。
+5. 把 bot 拉进群或直接私聊。
+
+生产部署时，在飞书后台切回 HTTP 回调模式，并给 `createLarkChannel` 传 `mode: "webhook"`。详见[生产部署](#生产部署)。
 
 ## 配置参考
 
-所有字段都可以通过选项传入，或从对应的环境变量读取（选项优先）。
+所有字段既能作为选项传入，也能从对应 env var 读取（选项优先）。
 
-| 字段 | 类型 | 必填 | 默认值 | 环境变量 |
+| 字段 | 类型 | 必填 | 默认 | env var |
 |---|---|---|---|---|
 | `appId` | `string` | 是 | — | `LARK_APP_ID` |
 | `appSecret` | `string` | 是 | — | `LARK_APP_SECRET` |
@@ -78,8 +88,10 @@ export default createLarkChannel({
 | `encryptKey` | `string` | 否 | — | `LARK_ENCRYPT_KEY` |
 | `baseUrl` | `string` | 否 | `https://open.feishu.cn` | `LARK_BASE_URL` |
 | `botOpenId` | `string` | 否 | — | `LARK_BOT_OPEN_ID` |
+| `mode` | `"long-connection" \| "webhook"` | 否 | `"long-connection"` | `LARK_MODE` |
+| `port` | `number` | 否 | `$PORT` 或 `2000` | `PORT` |
 | `webhookPath` | `string` | 否 | `/lark/webhook` | — |
-| `replyMode` | `"streaming" \| "static"` | 否 | `"streaming"` | — |
+| `replyMode` | `"post" \| "streaming" \| "static"` | 否 | `"post"` | `LARK_REPLY_MODE` |
 | `streamPatchIntervalMs` | `number` | 否 | `1000` | — |
 | `streamCreateThresholdMs` | `number` | 否 | `400` | — |
 | `dedupTtlMs` | `number` | 否 | `1_800_000`（30 分钟） | — |
@@ -88,11 +100,12 @@ export default createLarkChannel({
 | `maxRetries` | `number` | 否 | `2` | — |
 | `tokenRefreshBufferMs` | `number` | 否 | `300_000`（5 分钟） | — |
 | `signatureSkewMs` | `number` | 否 | `300_000`（5 分钟） | — |
+| `ackReaction` | `string \| readonly string[] \| false` | 否 | `"Typing"` | — |
 | `fetch` | `typeof fetch` | 否 | `globalThis.fetch` | — |
 
-## Feishu 与 Lark（国际版）
+## Feishu vs Lark（国际版）
 
-两套部署使用相同的 API。通过 `baseUrl` 切换：
+两个部署用同一套 API。通过 `baseUrl` 切换：
 
 ```ts
 createLarkChannel({
@@ -101,122 +114,141 @@ createLarkChannel({
 });
 ```
 
-或通过环境变量：`LARK_BASE_URL=https://open.larksuite.com`。
+或通过 env：`LARK_BASE_URL=https://open.larksuite.com`。
+
+## 回复模式
 
-## 流式 vs 静态模式
+- **`post`**（默认）：channel 等 `message.completed`，把回复作为 `msg_type: "post"` 富文本消息发出。**渲染为原生聊天消息大小**，完整支持 markdown（粗体、链接、代码、`<font>` 颜色 tag）。代价：不能流式——用户在 turn 完成时才看到回复。
+- **`streaming`**：channel 在第一个 delta 时创建交互卡片，节流地实时 patch（约 1 秒一次），turn 完成时收尾。**实时 UX 好**，但卡片文字比原生消息字号小（飞书把卡片当作「结构化内容」）。
+- **`static`**：和 `post` 一样等完成再发，但用交互卡片而非 post。适合需要卡片特性（按钮、多列布局）且不在乎字号小的场景。
 
-- **`streaming`**（默认）：通道在第一个 delta 时创建交互卡片，节流地实时 patch（约 1 秒一次），并在回合结束时收尾。用户体验最好。
-- **`static`**：通道等待 `message.completed`，然后一次性发送包含完整答案的卡片。API 调用量更低；当你撞上 Feishu 的 PATCH 限流时有用。
+流式节流通过 `streamPatchIntervalMs` 调整（值越小越平滑，但 API 调用越多）。
 
-通过 `streamPatchIntervalMs` 调节节流间隔（值越小越平滑，API 调用越多）。
+```bash
+LARK_REPLY_MODE=streaming   # 切到实时 patch
+```
 
-## 续接 token 与话题
+## Continuation token 与线程
 
-eve-lark 使用 chat id 加上话题根消息 id 作为会话续接 token：
+eve-lark 用 chat id 加线程 root message id 作为 session continuation token：
 
 ```
 <chat_id>:<root_message_id>
 ```
 
-对于顶层会话，root 是 `_`：
+对于顶层对话，root 是 `_`：
 
 ```
-oc_xxx:_       — 顶层对话
-oc_xxx:om_yyy  — om_yyy 话题中的回复
+oc_xxx:_       — 顶层
+oc_xxx:om_yyy  — 在 om_yyy 线程里的回复
 ```
 
-话题中的回复会跨回合保持话题锚点。该 token 按通道 id 命名空间化（eve 框架会前置通道文件名），所以同时部署多个自定义通道与 `lark` 共存是安全的。
+线程内的回复跨 turn 保留 thread anchor。token 由 channel id 命名空间隔离（eve 框架在前面拼上 channel 文件名），所以可以同时挂多个自定义 channel。
 
 ## 安全模型
 
-- **签名校验**：当设置了 `encryptKey` 时，每个入站 webhook 必须携带有效的 `X-Lark-Signature` 头。不匹配返回 HTTP 401。
-- **AES 解密**：设置了 `encryptKey` 时，使用 AES-256-CBC 解密 `encrypt` 信封，其中 `key = SHA256(encrypt_key)`，IV 取前 16 字节。
-- **时间戳偏移**：早于 `signatureSkewMs` 的请求会以 HTTP 408 拒绝。
-- **去重**：`event_id` 会被记住 `dedupTtlMs` 时间。重放返回 200 但不会重新启动回合。
-- **Serverless 注意事项**：去重是进程内的。多实例部署在极端时序窗口下可能会重复处理同一事件 —— 请把你的工具做成幂等的。
+- **签名校验**：设置了 `encryptKey` 时，每个入站 webhook 必须带有效的 `X-Lark-Signature` 头。不匹配返回 HTTP 401。
+- **AES 解密**：设置了 `encryptKey` 时，`encrypt` 信封用 AES-256-CBC 解密，`key = SHA256(encrypt_key)`，前 16 字节作为 IV。
+- **时间戳偏差**：超过 `signatureSkewMs` 的请求返回 HTTP 408。
+- **去重**：`event_id` 记忆 `dedupTtlMs` 时长。重放返回 200，不重新启动 turn。
+- **Serverless 注意**：去重是进程内的。多实例部署在极少数 timing 窗口下可能 double-process 事件——让你的工具幂等。
 
-## 文件与图片入站
+## 文件 & 图片入站
 
-入站的图片/文件消息会被转换成 eve 的 `UserContent` 文件 part。其 `data` 字段是一个指向 Lark 资源端点的 `URL`，所以 eve 的管道会调用通道的 `fetchFile` 钩子（使用 bot 的 `tenant_access_token`）把字节暂存给模型。
+入站的图片/文件消息会被转成 eve `UserContent` 的 file part。`data` 字段是指向飞书 resource endpoint 的 `URL`，所以 eve 的 pipeline 会调用 channel 的 `fetchFile` 钩子（用 bot 的 `tenant_access_token`）把字节 stage 给模型。
 
-如果你希望 URL part 直接透传而不暂存字节（例如在 eve sandbox 之外运行），不要设置 `encryptKey`，并在你的工具里检查 `attributes`。
+如果你想让 URL 部分直接透传（比如在 eve sandbox 外运行），不要设 `encryptKey`，改在工具里读 `attributes`。
 
 ## 错误
 
-eve-lark 抛出一个小的有类型层次结构：
+eve-lark 抛出一组类型化错误：
 
 ```
 LarkChannelError
-├── LarkConfigError        — 缺少必填选项
-├── LarkSignatureError     — 签名校验失败（很少抛出；通常返回 401 Response）
+├── LarkConfigError        — 缺必填选项
+├── LarkSignatureError     — 签名校验失败（很少抛；通常返回 401）
 ├── LarkDecryptError       — AES 解密失败
-└── LarkApiError           — Lark API 调用失败（携带 .code、.status、.body）
+└── LarkApiError           — Lark API 调用失败（带 .code、.status、.body）
 ```
 
-webhook 处理器返回结构化的 HTTP 响应，方便服务端处理：
+webhook handler 返回结构化 HTTP 响应，方便服务端处理：
 
-| 状态码 | 原因 |
+| Status | 原因 |
 |---|---|
-| 200 | Ack（成功或故意忽略的事件） |
-| 400 | JSON 无效 / 解密失败 |
-| 401 | 签名缺失/无效，或 verification token 不匹配 |
-| 408 | 超出时间戳偏移窗口 |
+| 200 | Ack（成功或有意忽略的事件） |
+| 400 | 无效 JSON / 解密失败 |
+| 401 | 签名缺失/无效或 verification token 不匹配 |
+| 408 | 时间戳偏差超过窗口 |
+| 413 | 请求 body 超过 1 MB 上限 |
 
-## 限制与路线图
+## 限制 & roadmap
 
-**v1 限制**：见 [暂不支持](#v1-暂不支持)。
+**v1 限制**：见[不在范围内](#不在-v1-范围内)。
 
-**v2 规划**（如果你希望优先实现某项，欢迎提 issue）：
-- 卡片动作按钮处理（交互式表单、确认流程）
+**v2 计划**（想优先哪个就开 issue）：
+- 完全自定义的卡片交互（agent 自渲染表单、确认流）
 - 音频 / 媒体入站转写
-- 可选的 Redis 支持的多实例去重
-- 用户级 OAuth（`user_access_token`），用于 Feishu API 工具
+- 可选的 Redis 后端去重，支持多实例部署
+- 用户级 OAuth（`user_access_token`）用于飞书 API 工具
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm test           # 运行 vitest 测试套件
-pnpm test:watch     # 交互式 watch 模式
+pnpm test           # 跑 vitest 测试套件
+pnpm test:watch     # 交互式 watch
 pnpm typecheck      # tsc --noEmit
 pnpm lint           # eslint
-pnpm build          # tsup 构建 → dist/
+pnpm build          # tsup build → dist/
 ```
 
-## 对接真实 Feishu 应用做冒烟测试
+## 真实飞书应用冒烟测试
+
+完整流程见 [`examples/README.md`](./examples/README.md)。TL;DR 跟[快速开始](#快速开始)一样：装依赖、填 `.env`、跑 `eve dev`。给 bot 发 `ping`，应该收到 `pong` 回复。
+
+## 生产部署
+
+生产环境切到 HTTP 回调模式：
+
+```ts
+// agent/channels/lark.ts
+export default createLarkChannel({
+  // ... 凭据 ...
+  mode: "webhook",   // 关闭 WSClient 副作用
+});
+```
 
-参见 [`examples/README.md`](./examples/README.md)，其中介绍了一种双进程的搭建方式，使用 Feishu 的长连接传输（无需公网 webhook URL）。简单来说：
+在飞书后台，把**事件订阅**从「长连接」切回**HTTP 回调**，URL 设为你部署的 agent 的 `/lark/webhook`。然后：
 
 ```bash
-pnpm build                                  # 构建 eve-lark，让 agent 能 import
-cp examples/agent/.env.example examples/agent/.env
-$EDITOR examples/agent/.env                 # 填入凭据
-cd examples/agent && pnpm install
-# 终端 A：
-cd examples/agent && pnpm dev               # eve dev server
-# 终端 B（在 repo 根目录）：
-pnpm tsx examples/ws-forwarder.ts           # Feishu WS → localhost HTTP
+eve build
+eve deploy          # 或：在有公网 URL 的服务器上跑 eve start
 ```
 
-在 Feishu 中向 bot 发送 `ping`，应该能收到 `pong` 的流式卡片回复。
+其他逻辑（签名、AES、去重、流式）不变。
 
-测试布局：
+测试目录：
 
 ```
 test/
-├── crypto.spec.ts              # 签名 & AES 向量（包含一个 round-trip 辅助函数）
-├── dedup.spec.ts               # TTL、FIFO 淘汰、惰性清理
+├── crypto.spec.ts              # 签名 & AES 测试向量（含 round-trip helper）
+├── dedup.spec.ts               # TTL、FIFO 淘汰、惰性 sweep
 ├── options.spec.ts             # env 回退、默认值、校验
-├── parse.spec.ts               # text/image/file/post/mention fixture
-├── lark-client.spec.ts         # token 互斥锁、重试策略（429/5xx/401）、nock 等价的 mock
+├── parse.spec.ts               # text/image/file/post/mention fixtures
+├── lark-client.spec.ts         # token mutex、retry policy（429/5xx/401）、mock fetch
 ├── streaming-controller.spec.ts # FSM 状态转换、节流、降级
-├── card.spec.ts                # 卡片构建器
-├── channel.spec.ts             # 端到端 webhook：校验、解密、去重、会话启动、流式串联
+├── card.spec.ts                # 卡片构造器
+├── feishu-emoji.spec.ts        # 飞书 emoji 白名单
+├── launcher-detection.spec.ts  # eve start launcher 进程识别
+├── long-connection.spec.ts     # WSClient 单例守卫、转发签名/AES
+├── channel.spec.ts             # 端到端 webhook：校验、解密、去重、session 启动、ack reaction
+├── ask-card.spec.ts            # ask_question 卡片构造器
+├── ask-flow.spec.ts            # ask_question 端到端：渲染、点击回调、freeform 拦截
 └── helpers/
-    ├── encrypt.ts              # 仅测试用的 AES 加密镜像
-    └── mock-fetch.ts           # 替代 nock 的微型 mock fetch（兼容原生 fetch）
+    ├── encrypt.ts              # 仅测试用的 AES cipher 镜像
+    └── mock-fetch.ts           # 替代 nock 的迷你 mock fetch
 ```
 
-## 协议
+## License
 
 MIT —— 见 [LICENSE](./LICENSE)。

package/dist/index.d.ts

@@ -197,9 +197,34 @@ type LarkCardElement = {
     }>;
 } | {
     tag: "action";
-    actions: LarkCardButton[];
+    actions: LarkCardActionItem[];
     layout?: "bisected" | "trisection" | "flow";
 };
+/** Union of action-row item shapes: buttons (yes/no confirm style) and
+ *  select menus (dropdowns for longer option lists). */
+type LarkCardActionItem = LarkCardButton | LarkCardSelectMenu;
+interface LarkCardSelectMenu {
+    tag: "select_static";
+    placeholder?: {
+        tag: "plain_text";
+        content: string;
+    };
+    /** Initially-selected option id (string). */
+    initial_option?: string;
+    /** Selectable options. `value` carries the optionId we get back in
+     *  `action.option` when the user picks one. */
+    options: Array<{
+        text: {
+            tag: "plain_text";
+            content: string;
+        };
+        value: string;
+    }>;
+    /** Same marker payload as a button so the dispatcher can recognise our
+     *  own callbacks. `optionId` is NOT set here — it comes back via
+     *  `action.option` instead. */
+    value?: Record<string, unknown>;
+}
 interface LarkCardButton {
     tag: "button";
     text: {

package/dist/index.js

@@ -564,26 +564,56 @@ function buildErrorCard(message) {
 }
 __name(buildErrorCard, "buildErrorCard");
 var ASK_BUTTON_VALUE_MARKER = "__eveLarkAsk";
+var ASK_OPTIONS_BUTTON_MAX = 3;
 function buildAskCard(request) {
   const elements = [
     { tag: "div", text: { tag: "lark_md", content: request.prompt } }
   ];
-  if (request.options && request.options.length > 0) {
-    const buttons = request.options.map((opt) => ({
-      tag: "button",
-      text: { tag: "plain_text", content: opt.label },
-      type: opt.style ?? "default",
-      value: {
-        [ASK_BUTTON_VALUE_MARKER]: true,
-        requestId: request.requestId,
-        optionId: opt.id
-      },
-      ...opt.description ? { confirm: { title: { tag: "plain_text", content: opt.label }, text: { tag: "plain_text", content: opt.description } } } : {}
-    }));
-    elements.push({ tag: "action", actions: buttons });
+  const optionCount = request.options?.length ?? 0;
+  if (optionCount > 0) {
+    const useSelect = request.display === "select" || optionCount > ASK_OPTIONS_BUTTON_MAX;
+    if (useSelect) {
+      elements.push({
+        tag: "action",
+        actions: [
+          {
+            tag: "select_static",
+            placeholder: { tag: "plain_text", content: "Select an option\u2026" },
+            options: request.options.map((opt) => ({
+              text: { tag: "plain_text", content: opt.label },
+              value: opt.id
+            })),
+            // Marker carries requestId; optionId is returned via action.option.
+            value: {
+              [ASK_BUTTON_VALUE_MARKER]: true,
+              requestId: request.requestId,
+              __larkSelect: true
+            }
+          }
+        ]
+      });
+    } else {
+      const buttons = request.options.map((opt) => ({
+        tag: "button",
+        text: { tag: "plain_text", content: opt.label },
+        type: opt.style ?? "default",
+        value: {
+          [ASK_BUTTON_VALUE_MARKER]: true,
+          requestId: request.requestId,
+          optionId: opt.id
+        },
+        ...opt.description ? {
+          confirm: {
+            title: { tag: "plain_text", content: opt.label },
+            text: { tag: "plain_text", content: opt.description }
+          }
+        } : {}
+      }));
+      elements.push({ tag: "action", actions: buttons });
+    }
   }
   if (request.allowFreeform) {
-    const hint = request.options && request.options.length > 0 ? "_\u2026or reply to this chat with your own answer_" : "_Reply to this chat with your answer_";
+    const hint = optionCount > 0 ? "_\u2026or reply to this chat with your own answer_" : "_Reply to this chat with your answer_";
     elements.push({ tag: "div", text: { tag: "lark_md", content: hint } });
   }
   return { config: { ...BASE_CONFIG }, elements };
@@ -1327,17 +1357,39 @@ function buildUserContent(text, files, options, messageId) {
   return parts;
 }
 __name(buildUserContent, "buildUserContent");
-function errMsgFrom(data, fallback) {
-  if (typeof data !== "object" || data === null) return fallback;
-  const err = data.error;
-  if (typeof err === "string") return err;
-  if (typeof err === "object" && err !== null) {
-    const msg = err.message;
-    if (typeof msg === "string") return msg;
-  }
-  return fallback;
+function formatErrorHint(data) {
+  if (typeof data !== "object" || data === null) return "";
+  const d = data;
+  const detailsName = typeof d.details === "object" && d.details !== null ? d.details.name : void 0;
+  const name = typeof detailsName === "string" && detailsName.length > 0 ? detailsName : void 0;
+  const message = typeof d.message === "string" ? d.message.trim() : "";
+  if (name && message.length > 0) return ` (${name}: ${truncateForDisplay(message)})`;
+  if (name) return ` (${name})`;
+  if (message.length > 0) return ` (${truncateForDisplay(message)})`;
+  return "";
 }
-__name(errMsgFrom, "errMsgFrom");
+__name(formatErrorHint, "formatErrorHint");
+function extractErrorId(details) {
+  if (typeof details === "object" && details !== null) {
+    const id = details.errorId;
+    return typeof id === "string" && id.length > 0 ? id : void 0;
+  }
+  return void 0;
+}
+__name(extractErrorId, "extractErrorId");
+function truncateForDisplay(s, max = 160) {
+  return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}\u2026`;
+}
+__name(truncateForDisplay, "truncateForDisplay");
+function formatFailureMessage(data, fallback, opts = { sentence: "turn" }) {
+  const hint = formatErrorHint(data);
+  const errorId = extractErrorId(data?.details);
+  const lead = opts.sentence === "session" ? "This session couldn't recover from an error" : "I hit an error while handling your request";
+  const idSuffix = errorId ? ` (Error id: ${errorId})` : "";
+  if (!hint && !errorId) return `\u26A0 ${fallback}`;
+  return `\u26A0 ${lead}${hint}.${idSuffix}`;
+}
+__name(formatFailureMessage, "formatFailureMessage");
 function createLarkChannel(optionsInput) {
   const options = resolveOptions(optionsInput);
   const client = new LarkClient(options);
@@ -1671,50 +1723,69 @@ function createLarkChannel(optionsInput) {
       return ackOk();
     }
     const requestId = typeof value.requestId === "string" ? value.requestId : "";
-    const optionId = typeof value.optionId === "string" ? value.optionId : "";
+    const optionId = (typeof value.optionId === "string" ? value.optionId : "") || (typeof evt.action?.option === "string" ? evt.action.option : "");
     if (!requestId) return ackOk();
     const pending = pendingInputsByRequestId.get(requestId);
     if (!pending) {
-      console.warn(`[eve-lark] card action for unknown requestId=${requestId} (already answered or expired)`);
-      return ackOk();
-    }
-    const resp = { requestId, optionId: optionId || void 0 };
-    const resumeToken = larkContinuationToken(pending.chatId, pending.parentId ?? pending.rootId ?? null);
-    const resumeAuth = {
-      authenticator: "lark",
-      principalType: "user",
-      principalId: evt.open_id,
-      attributes: {
-        chatId: pending.chatId,
-        rootMessageId: pending.rootId,
-        messageId: evt.open_message_id,
-        chatType: pending.request.display === "confirmation" ? "p2p" : "group"
-      }
-    };
-    try {
-      await helpers.send(
-        { inputResponses: [resp] },
-        { auth: resumeAuth, continuationToken: resumeToken }
-      );
-      console.log(`[eve-lark] ask answered via button click requestId=${requestId} optionId=${optionId}`);
-    } catch (e) {
-      console.error(
-        `[eve-lark] ask input-response send failed (requestId=${requestId}):`,
-        e instanceof Error ? e.message : e
+      console.warn(
+        `[eve-lark] card action for unknown requestId=${requestId} (already answered or expired)`
       );
+      return ackOk();
     }
     const selectedOpt = pending.request.options?.find((o) => o.id === optionId);
-    if (pending.cardMessageId && selectedOpt) {
-      try {
-        await client.patchCard({
-          messageId: pending.cardMessageId,
-          card: buildAskAnsweredCard(pending.request, { kind: "option", label: selectedOpt.label })
-        });
-      } catch (e) {
-        console.warn("[eve-lark] patchCard after ask-answer failed:", e instanceof Error ? e.message : e);
-      }
-    }
-    dropPendingInput(pending);
+    helpers.waitUntil(
+      (async () => {
+        if (pending.cardMessageId && selectedOpt) {
+          try {
+            await client.patchCard({
+              messageId: pending.cardMessageId,
+              card: buildAskAnsweredCard(pending.request, {
+                kind: "option",
+                label: selectedOpt.label
+              })
+            });
+          } catch (e) {
+            console.warn(
+              "[eve-lark] patchCard after ask-answer failed:",
+              e instanceof Error ? e.message : e
+            );
+          }
+        }
+        const resp = { requestId, optionId: optionId || void 0 };
+        const resumeToken = larkContinuationToken(
+          pending.chatId,
+          pending.parentId ?? pending.rootId ?? null
+        );
+        const resumeAuth = {
+          authenticator: "lark",
+          principalType: "user",
+          principalId: evt.open_id,
+          attributes: {
+            chatId: pending.chatId,
+            rootMessageId: pending.rootId,
+            messageId: evt.open_message_id,
+            chatType: pending.request.display === "confirmation" ? "p2p" : "group"
+          }
+        };
+        try {
+          await helpers.send(
+            { inputResponses: [resp] },
+            { auth: resumeAuth, continuationToken: resumeToken }
+          );
+          console.log(
+            `[eve-lark] ask answered via card action requestId=${requestId} optionId=${optionId}`
+          );
+        } catch (e) {
+          console.error(
+            `[eve-lark] ask input-response send failed (requestId=${requestId}):`,
+            e instanceof Error ? e.message : e
+          );
+        }
+        dropPendingInput(pending);
+      })().catch((e) => {
+        console.error("[eve-lark] card action background work failed:", e);
+      })
+    );
     return ackOk();
   }
   __name(handleCardAction, "handleCardAction");
@@ -1815,15 +1886,15 @@ function createLarkChannel(optionsInput) {
         console.warn(`[eve-lark] turn.failed: no session info (sessionId=${sessionId})`);
         return;
       }
-      const errMsg = errMsgFrom(data, "turn failed");
+      const userText = formatFailureMessage(data, "turn failed", { sentence: "turn" });
+      const errorId = extractErrorId(data?.details);
       console.warn(
-        `[eve-lark] turn.failed sessionId=${sessionId} chatId=${info.chatId} err="${errMsg.slice(0, 200)}"`
+        `[eve-lark] turn.failed sessionId=${sessionId} chatId=${info.chatId} err="${userText.slice(0, 200)}"` + (errorId ? ` errorId=${errorId}` : "")
       );
-      const userText = `\u26A0 ${errMsg}`;
       const ctrl = controllers.get(sessionId);
       if (ctrl) {
         try {
-          await ctrl.abort(errMsg);
+          await ctrl.abort(userText);
           console.log(`[eve-lark] error shown via streaming abort (sessionId=${sessionId})`);
         } catch (e) {
           console.warn(
@@ -1845,8 +1916,11 @@ function createLarkChannel(optionsInput) {
       dropController(sessionId);
     },
     async "session.failed"(data) {
-      const errMsg = errMsgFrom(data, "session failed");
-      console.error("[eve-lark] session.failed:", errMsg);
+      const userText = formatFailureMessage(data, "session failed", { sentence: "session" });
+      const errorId = extractErrorId(data?.details);
+      console.error(
+        `[eve-lark] session.failed: ${userText}` + (errorId ? ` (errorId=${errorId})` : "")
+      );
     }
   };
   const channel = defineChannel({