dsh-caduceus 0.1.0 → 0.4.1

package/README.md

@@ -1,96 +1,132 @@
 # dsh-caduceus
 
-把 **DeepSeek Harness（dsh）** 接到 **飞书 / Lark** 的插件：一个话题一个会话，人格块自动同步，过程卡片承载状态与答案，并带 `/status`、`/doctor`、`/sessions` 等命令。
+[中文](README.zh.md) / **English**
 
-## 安装
+[![npm version](https://img.shields.io/npm/v/dsh-caduceus.svg)](https://www.npmjs.com/package/dsh-caduceus)
+[![GitHub stars](https://img.shields.io/github/stars/ArtomYuan/dsh-caduceus.svg?style=social)](https://github.com/ArtomYuan/dsh-caduceus)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-### 路径 1：一次性命令行（推荐）
+**Use DeepSeek Harness in Feishu/Lark the way you use an agent — one topic, one session, a visible title, one card per turn.**
 
-发布到 npm 后，装包时直接放行依赖构建脚本：
+> Scope: the engine is still dsh. The agent loop, tools, sandbox and skills are unchanged; this package adds the conversation semantics and the chat surface around them.
 
-```bash
-dsh plugin --profile web add dsh-caduceus --allow-build=protobufjs
-```
-
-### 路径 2：先授权再装（不带 flag 也能装）
+## What you get
 
-在目标 profile 目录的 `pnpm-workspace.yaml` 里加：
-
-```yaml
-onlyBuiltDependencies:
-  - protobufjs
-```
+- **One scope, one session** — p2p, topic, and group-per-user sessions are kept separate.
+- **Visible titles** — generated from the first prompt and shown on the turn card.
+- **One card per turn** — status and answer live in the same card, edited in place; the final answer is not a second message.
+- **11 commands** — `/new`, `/sessions`, `/rename`, `/resume`, `/adopt`, `/status`, `/stop`, `/doctor`, `/selfcheck`, `/persona`, `/help`.
+- **Persona** — `SOUL.md` is synced into the `AGENTS.md` block, automatically at startup.
+- **Observability** — two-stage self-check, `/doctor`, and in-chat degradation warnings.
 
-然后正常安装即可：
+## Looks like
 
-```bash
-dsh plugin --profile web add dsh-caduceus
+```text
+飞书会话 · 过程
+会话：重构登录流程 · **运行中** · 步数 4 · 工具 3 · 已运行 12s
+最近：bash
+（the answer streams inside this card; at turn end the same card is frozen as 完成）
 ```
 
-### 路径 3：本地 tgz
+This is a text sketch, not a screenshot. At turn end the card shows the terminal state and the complete answer; a degraded card (preset not mounted) is marked `（preset 未挂载）`.
 
-```bash
-npm pack
-dsh plugin --profile web add ./dsh-caduceus-0.1.0.tgz --allow-build=protobufjs
-```
+## Requirements
 
-### 安装坑（实测 pnpm 11.7.0）
+| Requirement | Version / note |
+|:--|:--|
+| dsh | `>=0.2.1-rc.2` |
+| Node.js | `>=22.13` |
+| pnpm | `>=10` (pnpm 11 tested) |
+| Feishu / Lark app | One app can have **one long-connection consumer** at a time |
 
-- **flag 必须用等号**：`--allow-build=protobufjs` 可以；`--allow-build protobufjs`（空格）会报
-  `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE` 并安装失败。
-- **为什么需要放行**：`protobufjs` 是飞书 SDK 的传递依赖；pnpm ≥10 默认不执行依赖包的安装/构建脚本，
-  未放行时安装会以 `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: protobufjs@7.6.6` 失败。
-- **确认装上了**：安装后执行
+## Install
 
-  ```bash
-  dsh --profile web --dump-config | grep dsh-caduceus
-  ```
+1. Add the package (the build flag is required, see the note below):
 
-  应至少输出 2 行（两条 caduceus entry）。
+   ```bash
+   dsh plugin --profile web add dsh-caduceus --allow-build=protobufjs
+   ```
 
-安装/启用后由宿主统一重启 dsh；本包不控制服务。
+2. In the profile's `cordis.patch.yml`, give the `caduceus-gateway` row your Feishu credentials
+   (`appId` / `appSecret`, or `FEISHU_APP_ID` / `FEISHU_APP_SECRET`).
 
-## 配置
+3. Restart dsh from the host side. The log should contain `feishu long connection started`.
 
-在 profile 的 bundle 配置里提供：
+> **pnpm ≥10 note**: `protobufjs` is a transitive dependency of the Feishu SDK, and pnpm ≥10 does not
+> run dependency install/build scripts by default. Use `--allow-build=protobufjs` **with the equals
+> sign**; the space form (`--allow-build protobufjs`) fails with
+> `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE`. Without the flag the install fails with
+> `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: protobufjs@7.6.6`.
+> Alternatively, pre-authorize in the profile's `pnpm-workspace.yaml`:
 
-| 配置 | 默认 | 说明 |
-|:--|:--|:--|
-| `appId` / `appSecret` | — | 飞书应用凭证；也可用 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` |
-| `defaultCwd` | 当前进程 cwd | 新建会话的工作目录 |
-| `groupSessionsPerUser` | `true` | 普通群按发送者隔离会话；话题不受影响 |
-| `busyMode` | `queue` | 群里忙时的投递：`queue` / `steer` / `interrupt` |
-| `cardThrottleMs` | `400` | 过程卡 patch 节流（毫秒） |
-| `personaAutoSync` | `true` | 启动时把 SOUL 同步到 `$DSH_HOME/AGENTS.md` |
-| `agentPreset` | `standard` | 新会话挂载的 dsh agent preset |
-| `logLevel` | `info` | 文件日志级别：`info` / `debug` |
+```yaml
+onlyBuiltDependencies:
+  - protobufjs
+```
 
-人格：SOUL 源按 `$DSH_HOME/SOUL.md` → `$DSH_AGENTS_HOME/SOUL.md` 查找，投影到 `$DSH_HOME/AGENTS.md` 的标记块；命令见下。
+> Confirm the install with `dsh --profile web --dump-config | grep dsh-caduceus` — expect at least 2 lines.
 
-## 命令
+## Configure
 
-| 命令 | 说明 |
+| Key | Default | Description |
+|:--|:--|:--|
+| `appId` / `appSecret` | — | Feishu app credentials; `FEISHU_APP_ID` / `FEISHU_APP_SECRET` also work |
+| `defaultCwd` | process cwd | Working directory for new sessions |
+| `groupSessionsPerUser` | `true` | Isolate ordinary groups per sender; topics are unaffected |
+| `busyMode` | `queue` | Busy delivery: `queue` / `steer` / `interrupt` |
+| `cardThrottleMs` | `400` | Process-card patch throttle (ms) |
+| `personaAutoSync` | `true` | Sync SOUL into `$DSH_HOME/AGENTS.md` at startup |
+| `agentPreset` | `standard` | dsh agent preset mounted for new sessions |
+| `logLevel` | `info` | File log level: `info` / `debug` |
+| `approvalCard` | `true` | Send interactive approval cards (`allow once` / `reject`) |
+| `questionCard` | `true` | Send interactive question cards; single-select ≤4 options get buttons |
+| `interactiveTimeoutMs` | `300000` | How long an approval/question card waits before it expires |
+| `approvalPolicy` | `ask` | Session approval policy: `ask` (card confirmation, default) or `never` |
+| `reactions` | `true` | Emoji reactions on messages: `OnIt` while running, `DONE`/`CROSS_MARK` at turn end |
+| `reactionOnStart` | `OnIt` | Reaction added when a user message is accepted |
+| `reactionOnDone` | `DONE` | Reaction added when a turn completes |
+| `reactionOnFail` | `CROSS_MARK` | Reaction added when a turn errors/interrupts (falls back to `THINKING`) |
+| `gateRequireBotIdentity` | `true` | Group @ gate fails closed when the bot open id is unknown |
+
+## Commands
+
+| Command | Description |
 |:--|:--|
-| `/new` | 立即创建新会话（旧会话保留） |
-| `/sessions [--all]` | 列出当前会话或同聊天全部会话（含历史） |
-| `/rename <标题>` | 重命名当前会话 |
-| `/resume [id\|尾号]` | 恢复上一条或按完整 id / ≥8 位尾号切换 |
-| `/adopt <id\|尾号>` | 把无归属的历史会话收养到当前 scope |
-| `/selfcheck` | 立即重跑自检并输出逐项明细 |
-| `/doctor [--json]` | 体检报告：运行时 / 飞书 / 人格 / 会话 / 存储 / 版本 |
-| `/stop` | 中断正在运行的一轮 |
-| `/status` | 当前会话状态与自检摘要 |
-| `/persona [show\|sync]` | 查看或同步 SOUL 人格块 |
-| `/help` | 命令表 |
-
-## 故障排查
-
-- 启动日志里没有 `feishu long connection started`：先发 `/doctor` 看飞书凭证/长连接状态，再查文件日志。
-- 先发 `/doctor`：逐项看到 preset、工具数、人格投影、飞书连接、存储等状态；`/doctor --json` 可给脚本或他人排查。
-- 文件日志：`$DSH_HOME/caduceus/caduceus.log`（自动轮转，默认保留 3 份）。
-- 自检异常会同时在对话里发一条 `⚠ 自检异常 …（详情 /doctor）`；恢复后会发 `✓ 自检已恢复`。
-- 常见项：`preset:applied` 失败 = agent 没挂 preset（无工具/无人格）；`persona:fresh` 失败 = SOUL 与 `AGENTS.md` 不一致，发 `/persona sync` 或重启等自动同步。
-
-## 许可
-
-MIT。见 [LICENSE](LICENSE)。
+| `/new` | Materialize a new session immediately; keep the old one |
+| `/sessions [--all]` | List the current session, or every session of this chat |
+| `/rename <title>` | Rename the current session |
+| `/resume [id\|tail]` | Resume the previous session, or switch by full id / ≥8-char tail |
+| `/adopt <id\|tail>` | Adopt an unowned historical session into the current scope |
+| `/status` | Current session status plus the self-check summary |
+| `/stop` | Interrupt the running turn |
+| `/doctor [--json]` | Health report: runtime / Feishu / persona / session / storage / versions |
+| `/selfcheck` | Re-run both self-check stages and print every item |
+| `/persona [show\|sync]` | Show or sync the SOUL persona block |
+| `/help` | Command table |
+
+## Troubleshooting
+
+- **No `feishu long connection started` in the log**: run `/doctor` first, then check the file log at `$DSH_HOME/caduceus/caduceus.log`.
+- **`/doctor`**: shows runtime, Feishu, persona, session and storage checks; `/doctor --json` gives the same report for scripts or support.
+- **In-chat warnings**: self-check failures are posted into the conversation as `⚠ 自检异常 …（详情 /doctor）`; recovery posts `✓ 自检已恢复`.
+- **`preset:applied` fails**: the agent was created without a preset, so it has no tools and no persona. Check `agentPreset` and that the `agentPresets` service is available.
+- **`persona:fresh` fails**: `SOUL.md` and the block in `$DSH_HOME/AGENTS.md` differ. Run `/persona sync` or let the next startup auto-sync.
+- **Install failed with `ERR_PNPM_IGNORED_BUILDS` / `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE`**: see the pnpm note under Install.
+
+## Limitations
+
+- One Feishu/Lark app supports one long-connection consumer; do not run the same app in two dsh instances.
+- Command turns (`/doctor`, `/status`, `/sessions`, …) do not go through the agent, so tool counts may read `pending` until a normal message is sent.
+- The persona projection targets `$DSH_HOME/AGENTS.md`; a legacy block in `$DSH_AGENTS_HOME/AGENTS.md` is only reported and never deleted.
+- The file log rotates at 5 MB and keeps 3 files.
+- There is no separate Web UI install wizard; installation is through the dsh CLI.
+
+## Docs
+
+- [docs/DESIGN.md](docs/DESIGN.md) — design and surface semantics
+- [docs/VERIFY.md](docs/VERIFY.md) — isolated-profile verification steps
+- [docs/](docs/) — slice notes (`SLICE*.md`)
+
+## License
+
+[MIT](LICENSE) © 2026 ArtomYuan

package/README.zh.md

@@ -0,0 +1,131 @@
+# dsh-caduceus
+
+[English](README.md) / **中文**
+
+[![npm version](https://img.shields.io/npm/v/dsh-caduceus.svg)](https://www.npmjs.com/package/dsh-caduceus)
+[![GitHub stars](https://img.shields.io/github/stars/ArtomYuan/dsh-caduceus.svg?style=social)](https://github.com/ArtomYuan/dsh-caduceus)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**在飞书/Lark 里像用 agent 一样用 DeepSeek Harness——一个话题一个会话，标题可见，每回合一张卡。**
+
+> 作用域：引擎仍是 dsh。agent loop、工具、沙箱、skills 都不变；本包只提供会话语义与聊天界面。
+
+## What you get（能拿到什么）
+
+- **一个 scope 一个会话** — 私聊、话题、普通群按发送者隔离。
+- **标题可见** — 由第一条 prompt 生成，显示在回合卡上。
+- **每回合一张卡** — 状态与答案在同一张卡里，原地编辑；终稿不再另发一条消息。
+- **11 条命令** — `/new`、`/sessions`、`/rename`、`/resume`、`/adopt`、`/status`、`/stop`、`/doctor`、`/selfcheck`、`/persona`、`/help`。
+- **人格** — `SOUL.md` 同步到 `AGENTS.md` 的标记块，启动时自动执行。
+- **可观测性** — 两阶段自检、`/doctor`、对话内的降级提示。
+
+## Looks like（长什么样）
+
+```text
+飞书会话 · 过程
+会话：重构登录流程 · **运行中** · 步数 4 · 工具 3 · 已运行 12s
+最近：bash
+（正文在这张卡里滚动；收尾时同一张卡定格为「完成」）
+```
+
+这是文本示意，不是截图。收尾时卡内显示终态与完整答案；降级（preset 未挂载）时状态行会标 `（preset 未挂载）`。
+
+## Requirements（前置要求）
+
+| 要求 | 版本 / 说明 |
+|:--|:--|
+| dsh | `>=0.2.1-rc.2` |
+| Node.js | `>=22.13` |
+| pnpm | `>=10`（实测 11） |
+| 飞书/Lark 应用 | 一个应用同一时间只能有**一路长连接**消费者 |
+
+## Install（安装）
+
+1. 装包（必须带 build flag，说明见下）：
+
+   ```bash
+   dsh plugin --profile web add dsh-caduceus --allow-build=protobufjs
+   ```
+
+2. 在 profile 的 `cordis.patch.yml` 里，给 `caduceus-gateway` 这一行填飞书凭证
+   （`appId` / `appSecret`，或用 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`）。
+
+3. 由宿主侧重启 dsh。日志里应出现 `feishu long connection started`。
+
+> **pnpm ≥10 注意**：`protobufjs` 是飞书 SDK 的传递依赖；pnpm ≥10 默认不执行依赖包的安装/构建脚本。
+> 必须用**等号**形式 `--allow-build=protobufjs`；空格形式（`--allow-build protobufjs`）会报
+> `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE`。不带 flag 会以
+> `ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: protobufjs@7.6.6` 失败。
+> 也可以在 profile 的 `pnpm-workspace.yaml` 里预先放行：
+
+```yaml
+onlyBuiltDependencies:
+  - protobufjs
+```
+
+> 安装后用 `dsh --profile web --dump-config | grep dsh-caduceus` 确认——应至少 2 行。
+
+## Configure（配置）
+
+| 配置 | 默认 | 说明 |
+|:--|:--|:--|
+| `appId` / `appSecret` | — | 飞书应用凭证；也可用 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` |
+| `defaultCwd` | 当前进程 cwd | 新建会话的工作目录 |
+| `groupSessionsPerUser` | `true` | 普通群按发送者隔离会话；话题不受影响 |
+| `busyMode` | `queue` | 忙碌时投递：`queue` / `steer` / `interrupt` |
+| `cardThrottleMs` | `400` | 过程卡 patch 节流（毫秒） |
+| `personaAutoSync` | `true` | 启动时把 SOUL 同步到 `$DSH_HOME/AGENTS.md` |
+| `agentPreset` | `standard` | 新会话挂载的 dsh agent preset |
+| `logLevel` | `info` | 文件日志级别：`info` / `debug` |
+| `approvalCard` | `true` | 发交互审批卡（允许一次 / 拒绝） |
+| `questionCard` | `true` | 发交互选项卡；单选且 ≤4 个选项时显示按钮 |
+| `interactiveTimeoutMs` | `300000` | 审批/选项卡等待多久后过期 |
+| `approvalPolicy` | `ask` | 会话审批策略：`ask`（弹卡确认，默认）或 `never` |
+| `reactions` | `true` | 消息表情反馈：处理中 `OnIt`，结束 `DONE`/`CROSS_MARK` |
+| `reactionOnStart` | `OnIt` | 收到用户消息时添加的表情 |
+| `reactionOnDone` | `DONE` | 回合完成时添加的表情 |
+| `reactionOnFail` | `CROSS_MARK` | 回合出错/中断时添加的表情（失败退回 `THINKING`） |
+| `gateRequireBotIdentity` | `true` | bot open id 未知时群 @ 门禁 fail-closed（false 恢复旧放行） |
+
+## 命令
+
+| 命令 | 说明 |
+|:--|:--|
+| `/new` | 立即创建新会话；旧会话保留 |
+| `/sessions [--all]` | 列出当前会话，或本聊天的全部会话 |
+| `/rename <标题>` | 重命名当前会话 |
+| `/resume [id\|尾号]` | 恢复上一条，或按完整 id / ≥8 位尾号切换 |
+| `/adopt <id\|尾号>` | 把无归属的历史会话收养到当前 scope |
+| `/status` | 当前会话状态 + 自检摘要 |
+| `/stop` | 中断正在运行的一轮 |
+| `/doctor [--json]` | 体检报告：运行时 / 飞书 / 人格 / 会话 / 存储 / 版本 |
+| `/selfcheck` | 立即重跑两阶段自检并输出逐项明细 |
+| `/persona [show\|sync]` | 查看或同步 SOUL 人格块 |
+| `/help` | 命令表 |
+
+## Troubleshooting（故障排查）
+
+- **日志里没有 `feishu long connection started`**：先发 `/doctor`，再看文件日志 `$DSH_HOME/caduceus/caduceus.log`。
+- **`/doctor`**：逐项显示运行时、飞书、人格、会话、存储状态；`/doctor --json` 可给脚本或求助对象。
+- **对话内提示**：自检失败会发 `⚠ 自检异常 …（详情 /doctor）`；恢复会发 `✓ 自检已恢复`。
+- **`preset:applied` 失败**：agent 没挂 preset，等于没工具、没人格；检查 `agentPreset` 与 `agentPresets` 服务。
+- **`persona:fresh` 失败**：`SOUL.md` 与 `$DSH_HOME/AGENTS.md` 的块不一致；发 `/persona sync` 或等下次启动自动同步。
+- **安装报 `ERR_PNPM_IGNORED_BUILDS` / `ERR_PNPM_ALLOW_BUILD_MISSING_PACKAGE`**：见 Install 的 pnpm 说明。
+
+## Limitations（限制）
+
+- 一个飞书/Lark 应用只支持一路长连接消费者；不要在两个 dsh 实例里跑同一个应用。
+- 命令回合（`/doctor`、`/status`、`/sessions` 等）不经过 agent，工具数在发正常消息前可能显示 `pending`。
+- 人格投影目标是 `$DSH_HOME/AGENTS.md`；旧位置 `$DSH_AGENTS_HOME/AGENTS.md` 的块只会被提示，不会自动删除。
+- 文件日志 5 MB 轮转，保留 3 份。
+- 没有独立的 Web UI 安装向导；安装走 dsh CLI。
+
+## Docs（文档）
+
+- [docs/DESIGN.md](docs/DESIGN.md) — 设计与界面语义
+- [docs/VERIFY.md](docs/VERIFY.md) — 隔离 profile 验证步骤
+- [docs/](docs/) — 各刀记录（`SLICE*.md`）
+
+## License（许可）
+
+[MIT](LICENSE) © 2026 ArtomYuan

package/dist/bridge/bridge.d.ts

@@ -19,6 +19,15 @@ export declare class Bridge {
     handleSessionEvent(session: {
         readonly id: string;
     }, event: StatusEventLike): Promise<void>;
+    /**
+     * Send an interactive card the same way process cards go out: reply into the
+     * originating topic/thread when the session still has a live scope. Falls
+     * back to a chat send only when the scope state is gone.
+     */
+    sendInteractiveCard(sessionId: string, card: FeishuCard): Promise<{
+        readonly messageId: string;
+        readonly threadId?: string;
+    }>;
 }
 /** Build the process card for one snapshot (exported for render tests). */
 export declare function progressCardForSnapshot(snapshot: StatusSnapshot, sessionTitle: string | undefined, recentEvent: string, tail: string, now: number, presetMissing?: boolean): FeishuCard;

package/dist/bridge/bridge.js

@@ -81,6 +81,8 @@ export class Bridge {
     #selfCheck;
     #agentCtxBySession = new Map();
     #toolsCheckedSessions = new Set();
+    #approvalMissingWarned = false;
+    #botIdentityErrorLogged = false;
     /** Last fail-id set already notified into the conversation. */
     #selfCheckNotifiedSignature;
     /** Session ids whose preset mount failed (shown as `（preset 未挂载）`). */
@@ -88,6 +90,7 @@ export class Bridge {
     #sessionTitleProvider;
     #queue = new ScopeQueue();
     #states = new Map();
+    #chatIdBySession = new Map();
     #scopeBySession = new Map();
     constructor(options) {
         this.#options = options;
@@ -117,6 +120,12 @@ export class Bridge {
             if (sessionId !== undefined)
                 this.#scopeBySession.set(sessionId, key);
         }
+        if (options.interactive !== undefined && options.rootCtx !== undefined) {
+            options.interactive.registerRoot(options.rootCtx, {
+                ownsSession: (sessionId) => this.ownsSession(sessionId),
+                contextFor: (sessionId) => this.#interactiveContext(sessionId),
+            });
+        }
     }
     /** True when a session id belongs to a scope this bridge renders. */
     ownsSession(sessionId) {
@@ -124,6 +133,17 @@ export class Bridge {
     }
     /** Process one inbound message (serialized per scope). */
     async handleInbound(message) {
+        // Bot identity may have failed at startup; retry on the next group message
+        // before deciding, so a late bot/v3/info success restores normal gating.
+        if (message.chatType === 'group' && (this.#transport.getBotOpenId?.() ?? '').length === 0) {
+            try {
+                await this.#transport.refreshBotOpenId?.();
+            }
+            catch (error) {
+                this.#logger.warn(`bot identity refresh failed: ${errorMessage(error)}`);
+            }
+        }
+        const botOpenId = this.#transport.getBotOpenId?.();
         const decision = evaluateGate({
             chatType: message.chatType,
             chatId: message.chatId,
@@ -131,9 +151,8 @@ export class Bridge {
             senderOpenId: message.senderOpenId,
             text: message.text,
             ...(message.mentions === undefined ? {} : { mentions: message.mentions }),
-            ...(this.#transport.getBotOpenId?.() === undefined
-                ? {}
-                : { botOpenId: this.#transport.getBotOpenId?.() }),
+            ...(botOpenId === undefined ? {} : { botOpenId }),
+            requireBotIdentity: this.#config.gateRequireBotIdentity !== false,
             allowedChats: this.#config.allowedChats,
             allowedUsers: this.#config.allowedUsers,
         });
@@ -142,6 +161,12 @@ export class Bridge {
             ...(message.threadId === undefined ? {} : { threadId: message.threadId }),
             senderOpenId: message.senderOpenId,
         });
+        if (!decision.accept && decision.reason === 'bot-identity-unknown') {
+            if (!this.#botIdentityErrorLogged) {
+                this.#botIdentityErrorLogged = true;
+                this.#logger.error('gate: bot identity unknown; group @ messages are rejected until resolved');
+            }
+        }
         if (!decision.accept)
             return;
         await this.#queue.run(scopeKey(message.chatType, message.chatId, message.threadId, message.senderOpenId, this.#config.groupSessionsPerUser), () => this.#processInbound(message));
@@ -218,6 +243,7 @@ export class Bridge {
     async #processInbound(message) {
         const state = this.#stateFor(message);
         state.lastInboundMessageId = message.messageId;
+        state.ownerOpenId = message.senderOpenId;
         // Startup-stage failures have no session to notify yet; the first message
         // with a session catches up here (once per fail combination).
         await this.#maybeNotifySelfCheck(state);
@@ -226,6 +252,8 @@ export class Bridge {
             await this.#handleSlash(state, message.text);
             return;
         }
+        state.reactionQueue.push(message.messageId);
+        this.#startReaction(state, message.messageId);
         await this.#deliverTurn(state, message.text);
     }
     async #handleSlash(state, raw) {
@@ -447,6 +475,7 @@ export class Bridge {
             if (notice !== undefined)
                 await this.#replyText(state, notice);
         }
+        await this.#finishReactions(state, kind);
         state.lastOutput = '';
     }
     #finalCardInput(state, snapshot, body) {
@@ -698,11 +727,20 @@ export class Bridge {
     async #switchSession(state, target, verb = '已恢复会话') {
         const current = state.sessionId ?? this.#sessionMap.get(state.key);
         try {
-            const { agent } = await this.#agents.resume({ resumeSessionId: target });
+            const persistedPreset = this.#sessionPresetLookup?.(target);
+            const { agent } = await this.#agents.resume({
+                resumeSessionId: target,
+                setup: async (agentCtx) => {
+                    this.#agentCtxBySession.set(target, agentCtx);
+                    if (persistedPreset === undefined)
+                        await this.#mountPreset(target, agentCtx);
+                },
+            });
             if (current !== undefined && current !== target) {
                 state.previousSessionId = current;
                 state.previousSessionAt = this.#lastActivityAt(state) ?? this.#now();
             }
+            this.#applyApprovalPolicy(agent);
             this.#sessionMap.set(state.key, target);
             state.sessionId = target;
             state.pendingCreate = false;
@@ -775,6 +813,45 @@ export class Bridge {
             this.#agentPresetsCache = service;
         return service;
     }
+    /**
+     * Apply the configured session approval policy to a freshly created/resumed
+     * agent. Missing service warns once; setPolicy errors never block the turn.
+     */
+    #applyApprovalPolicy(agent) {
+        const policy = this.#options.approvalPolicy ?? 'ask';
+        this.#logger.info(`agent approval policy=${policy}`);
+        const provider = this.#options.approvalProvider;
+        if (provider === undefined)
+            return;
+        const service = provider();
+        if (service === undefined) {
+            if (!this.#approvalMissingWarned) {
+                this.#approvalMissingWarned = true;
+                this.#logger.warn('approval service unavailable; session approval policy not applied');
+            }
+            return;
+        }
+        try {
+            service.setPolicy(agent, policy);
+        }
+        catch (error) {
+            this.#logger.warn(`agent approval policy=${policy} failed: ${errorMessage(error)}`);
+        }
+    }
+    #interactiveContext(sessionId) {
+        const key = this.#scopeBySession.get(sessionId);
+        if (key === undefined)
+            return undefined;
+        const state = this.#states.get(key);
+        if (state === undefined || state.ownerOpenId === undefined)
+            return undefined;
+        return {
+            scopeKey: state.key,
+            chatId: state.chatId,
+            ownerOpenId: state.ownerOpenId,
+            sessionId,
+        };
+    }
     /**
      * Mount the configured agent preset in the unpublished agent scope.
      * Idempotent for resumes: a context that already reports a composed preset is
@@ -827,6 +904,7 @@ export class Bridge {
         catch (error) {
             this.#logger.warn(`ownership write failed for ${sessionId}: ${errorMessage(error)}`);
         }
+        this.#applyApprovalPolicy(agent);
         await this.#runSelfCheckStageB(state, sessionId);
         return { agent };
     }
@@ -1020,6 +1098,7 @@ export class Bridge {
                 },
             });
             this.#bindSession(state, String(agent.session.id));
+            this.#applyApprovalPolicy(agent);
             await this.#runSelfCheckStageB(state, sessionId);
             return { agent, sessionId, cwd };
         }
@@ -1045,8 +1124,77 @@ export class Bridge {
                 this.#scopeBySession.delete(id);
         }
         this.#scopeBySession.set(sessionId, state.key);
+        this.#chatIdBySession.set(sessionId, state.chatId);
         state.sessionId = sessionId;
     }
+    /**
+     * Send an interactive card the same way process cards go out: reply into the
+     * originating topic/thread when the session still has a live scope. Falls
+     * back to a chat send only when the scope state is gone.
+     */
+    async sendInteractiveCard(sessionId, card) {
+        const key = this.#scopeBySession.get(sessionId);
+        const state = key === undefined ? undefined : this.#states.get(key);
+        if (state === undefined) {
+            const chatId = this.#chatIdBySession.get(sessionId) ?? '';
+            this.#logger.warn(`interactive: no scope state for ${sessionId}; falling back to chat send`);
+            return this.#transport.sendCard(chatId, card);
+        }
+        const sent = await this.#sendNewCard(state, card);
+        return {
+            ...sent,
+            ...(state.threadId === undefined ? {} : { threadId: state.threadId }),
+        };
+    }
+    #startReaction(state, messageId) {
+        if (this.#config.reactions === false)
+            return;
+        const promise = this.#safeAddReaction(messageId, this.#config.reactionOnStart ?? 'OnIt');
+        state.reactionStarts.set(messageId, promise);
+        void promise;
+    }
+    /** Remove the start reaction, then add the terminal reaction (best effort). */
+    async #finishReactions(state, turnKind) {
+        if (this.#config.reactions === false)
+            return;
+        const messageId = state.reactionQueue.shift();
+        if (messageId === undefined)
+            return;
+        const start = state.reactionStarts.get(messageId);
+        state.reactionStarts.delete(messageId);
+        const reactionId = start === undefined ? undefined : await start;
+        if (reactionId !== undefined)
+            await this.#safeRemoveReaction(messageId, reactionId);
+        const completed = turnKind === 'completed';
+        const emoji = completed
+            ? (this.#config.reactionOnDone ?? 'DONE')
+            : (this.#config.reactionOnFail ?? 'CROSS_MARK');
+        const added = await this.#safeAddReaction(messageId, emoji);
+        if (!completed && added === undefined && emoji !== 'THINKING') {
+            await this.#safeAddReaction(messageId, 'THINKING');
+        }
+    }
+    async #safeAddReaction(messageId, emojiType) {
+        try {
+            return await this.#transport.addReaction(messageId, emojiType);
+        }
+        catch (error) {
+            this.#logReactionSkipped(error);
+            return undefined;
+        }
+    }
+    async #safeRemoveReaction(messageId, reactionId) {
+        try {
+            await this.#transport.removeReaction(messageId, reactionId);
+        }
+        catch (error) {
+            this.#logReactionSkipped(error);
+        }
+    }
+    #logReactionSkipped(error) {
+        const code = error.code;
+        this.#logger.debug(`reaction skipped: ${typeof code === 'number' ? code : 'unknown'} ${errorMessage(error)}`);
+    }
     #stateFor(message) {
         const key = scopeKey(message.chatType, message.chatId, message.threadId, message.senderOpenId, this.#config.groupSessionsPerUser);
         const existing = this.#states.get(key);
@@ -1061,6 +1209,8 @@ export class Bridge {
             running: false,
             status: new StatusTracker(),
             lastOutput: '',
+            reactionQueue: [],
+            reactionStarts: new Map(),
         };
         this.#states.set(key, created);
         return created;
@@ -1080,7 +1230,7 @@ export class Bridge {
     }
     async #sendNewCard(state, card) {
         if (state.lastInboundMessageId !== undefined) {
-            return this.#transport.reply(state.chatId, state.lastInboundMessageId, { kind: 'card', card }, { threadId: state.threadId });
+            return this.#transport.reply(state.chatId, state.lastInboundMessageId, { kind: 'card', card }, state.threadId === undefined ? {} : { threadId: state.threadId });
         }
         return this.#transport.sendCard(state.chatId, card);
     }