dsh-caduceus 0.1.1 → 0.4.1

package/README.md

@@ -78,6 +78,15 @@ onlyBuiltDependencies:
 | `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
 

package/README.zh.md

@@ -77,6 +77,15 @@ onlyBuiltDependencies:
 | `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 恢复旧放行） |
 
 ## 命令
 

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);
     }

package/dist/bridge/types.d.ts

@@ -13,10 +13,17 @@ import type { HarnessCommandResult } from '../commands/harness.js';
 import type { LoggerLike } from '../logger.js';
 import type { Clock } from '../render/stream.js';
 import type { DoctorInputs, DoctorSessionInfo } from '../doctor.js';
+import type { InteractiveRuntime } from '../interactive/runtime.js';
 import type { SessionStore } from '../session-key.js';
 import type { Transport } from '../transport/types.js';
 /** Busy-turn delivery policy (design doc §6 L3). */
 export type BusyMode = 'queue' | 'steer' | 'interrupt';
+/** Session approval policy understood by dsh's approval service. */
+export type ApprovalPolicy = 'ask' | 'never';
+/** The slice of dsh's approval service the bridge needs. */
+export interface ApprovalServiceLike {
+    setPolicy(agent: AgentLike, policy: ApprovalPolicy): void;
+}
 /** Structural subset of a dsh session. */
 export interface SessionLike {
     readonly id: string;
@@ -86,6 +93,13 @@ export interface BridgeConfig {
     readonly groupSessionsPerUser: boolean;
     /** Agent preset mounted for caduceus sessions (default `standard`). */
     readonly agentPreset?: string;
+    /** Emoji reactions enabled (default true). */
+    readonly reactions?: boolean;
+    readonly reactionOnStart?: string;
+    readonly reactionOnDone?: string;
+    readonly reactionOnFail?: string;
+    /** Default true: group @ gate fails closed when bot open id is unknown. */
+    readonly gateRequireBotIdentity?: boolean;
 }
 /** Everything the bridge needs; unit tests provide fakes for every seam. */
 export interface BridgeOptions {
@@ -111,6 +125,14 @@ export interface BridgeOptions {
     readonly persona?: (action: 'show' | 'sync') => Promise<PersonaCommandResult>;
     /** Time source for elapsed rendering; defaults to the clock. */
     readonly now?: () => number;
+    /** Interactive approval/question cards (wired by the gateway). */
+    readonly interactive?: InteractiveRuntime;
+    /** Plugin root Cordis context; answerers register here once, not per agent. */
+    readonly rootCtx?: unknown;
+    /** Lazily resolve dsh's approval service (agent-scoped setPolicy). */
+    readonly approvalProvider?: () => ApprovalServiceLike | undefined;
+    /** Desired session approval policy (default `ask`). */
+    readonly approvalPolicy?: ApprovalPolicy;
     /** `/doctor` data collector (wired by the gateway; not available in tests by default). */
     readonly doctorInputs?: (session: DoctorSessionInfo) => DoctorInputs | Promise<DoctorInputs>;
     /** Optional self-check controller (`/status`, `/selfcheck`, stage B). */

package/dist/commands/parse.d.ts

@@ -1,14 +1,3 @@
-/**
- * Slash-command parsing for the Feishu surface. Pure: no I/O, no side effects.
- *
- * Eleven commands are owned by dsh-caduceus: `/new`, `/sessions`, `/rename`,
- * `/resume`, `/adopt`, `/stop`, `/status`, `/persona`, `/help`. Everything else — unknown slash
- * commands such as `/compact` and all ordinary user text — comes back as
- * `{ kind: 'passthrough', raw }` so the caller can forward it unchanged to the
- * dsh command registry or the agent (design doc §6 L3).
- *
- * @module dsh-caduceus/commands/parse
- */
 /** Commands dsh-caduceus owns. Keep in sync with README's command table. */
 export declare const COMMAND_NAMES: readonly ["new", "sessions", "rename", "resume", "adopt", "selfcheck", "doctor", "stop", "status", "persona", "help"];
 export type CommandName = (typeof COMMAND_NAMES)[number];

package/dist/commands/parse.js

@@ -9,6 +9,7 @@
  *
  * @module dsh-caduceus/commands/parse
  */
+import { stripLeadingMentions } from '../mentions.js';
 /** Commands dsh-caduceus owns. Keep in sync with README's command table. */
 export const COMMAND_NAMES = ['new', 'sessions', 'rename', 'resume', 'adopt', 'selfcheck', 'doctor', 'stop', 'status', 'persona', 'help'];
 /** Command metadata; `helpText()` and the README command table both derive from it. */
@@ -37,7 +38,10 @@ function usageResult(command, reason) {
  * never rewrites a user's text.
  */
 export function parseCommand(raw) {
-    const trimmed = raw.trim();
+    // A topic/group message may arrive as "@_user_1 /stop" (Feishu's mention
+    // placeholder). Strip only the leading mentions before command detection;
+    // passthrough still forwards the ORIGINAL bytes.
+    const trimmed = stripLeadingMentions(raw).trim();
     if (!trimmed.startsWith('/'))
         return { kind: 'passthrough', raw };
     const match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(trimmed);

package/dist/config.d.ts

@@ -1,5 +1,5 @@
 import z from '@deepseek-ai/schemastery';
-import type { BridgeConfig, BusyMode } from './bridge/types.js';
+import type { ApprovalPolicy, BridgeConfig, BusyMode } from './bridge/types.js';
 /** Raw entry config as written in the profile. */
 export interface GatewayConfig {
     readonly appId?: string;
@@ -17,6 +17,24 @@ export interface GatewayConfig {
     readonly personaAutoSync?: boolean;
     /** Agent preset mounted for caduceus-created sessions (default `standard`). */
     readonly agentPreset?: string;
+    /** Send interactive approval cards (default true). */
+    readonly approvalCard?: boolean;
+    /** Send interactive question cards (default true). */
+    readonly questionCard?: boolean;
+    /** Interactive card timeout in ms (default 300000). */
+    readonly interactiveTimeoutMs?: number;
+    /** Session approval policy; IM humans are present, so default `ask`. */
+    readonly approvalPolicy?: ApprovalPolicy;
+    /** Emoji reactions on inbound/turn-end (default true). */
+    readonly reactions?: boolean;
+    /** Emoji added on accept (default `OnIt`). */
+    readonly reactionOnStart?: string;
+    /** Emoji added on completed turn (default `DONE`). */
+    readonly reactionOnDone?: string;
+    /** Emoji added on failed/interrupted turn (default `CROSS_MARK`). */
+    readonly reactionOnFail?: string;
+    /** Require the bot's own open id for the group @ gate (default true). */
+    readonly gateRequireBotIdentity?: boolean;
 }
 /** Schemastery schema for the `caduceus-gateway` entry. */
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
@@ -31,6 +49,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     logLevel: z<"info" | "debug", "info" | "debug", "plain">;
     personaAutoSync: z<boolean, boolean, "plain">;
     agentPreset: z<string, string, "plain">;
+    approvalCard: z<boolean, boolean, "plain">;
+    questionCard: z<boolean, boolean, "plain">;
+    interactiveTimeoutMs: z<number, number, "plain">;
+    approvalPolicy: z<"ask" | "never", "ask" | "never", "plain">;
+    reactions: z<boolean, boolean, "plain">;
+    reactionOnStart: z<string, string, "plain">;
+    reactionOnDone: z<string, string, "plain">;
+    reactionOnFail: z<string, string, "plain">;
+    gateRequireBotIdentity: z<boolean, boolean, "plain">;
 }>>, Schemastery.ObjectT<NoInfer<{
     appId: z<string, string, "plain">;
     appSecret: z<string, string, "plain">;
@@ -43,6 +70,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     logLevel: z<"info" | "debug", "info" | "debug", "plain">;
     personaAutoSync: z<boolean, boolean, "plain">;
     agentPreset: z<string, string, "plain">;
+    approvalCard: z<boolean, boolean, "plain">;
+    questionCard: z<boolean, boolean, "plain">;
+    interactiveTimeoutMs: z<number, number, "plain">;
+    approvalPolicy: z<"ask" | "never", "ask" | "never", "plain">;
+    reactions: z<boolean, boolean, "plain">;
+    reactionOnStart: z<string, string, "plain">;
+    reactionOnDone: z<string, string, "plain">;
+    reactionOnFail: z<string, string, "plain">;
+    gateRequireBotIdentity: z<boolean, boolean, "plain">;
 }>>, "plain">;
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export declare const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -56,6 +92,17 @@ export declare const DEFAULT_LOG_LEVEL: 'info' | 'debug';
 export declare const DEFAULT_PERSONA_AUTO_SYNC = true;
 /** Default agent preset for caduceus sessions. */
 export declare const DEFAULT_AGENT_PRESET = "standard";
+/** Default message reactions. */
+export declare const DEFAULT_REACTIONS = true;
+export declare const DEFAULT_REACTION_ON_START = "OnIt";
+export declare const DEFAULT_REACTION_ON_DONE = "DONE";
+export declare const DEFAULT_REACTION_ON_FAIL = "CROSS_MARK";
+/** Default session approval policy: ask, so dangerous actions prompt a card. */
+export declare const DEFAULT_APPROVAL_POLICY: ApprovalPolicy;
+/** Default interactive-card switches/timeout. */
+export declare const DEFAULT_APPROVAL_CARD = true;
+export declare const DEFAULT_QUESTION_CARD = true;
+export declare const DEFAULT_INTERACTIVE_TIMEOUT_MS = 300000;
 export interface ResolvedGatewayConfig {
     readonly credentials?: {
         readonly appId: string;
@@ -65,6 +112,10 @@ export interface ResolvedGatewayConfig {
     readonly logLevel: 'info' | 'debug';
     readonly personaAutoSync: boolean;
     readonly agentPreset: string;
+    readonly approvalCard: boolean;
+    readonly questionCard: boolean;
+    readonly interactiveTimeoutMs: number;
+    readonly approvalPolicy: ApprovalPolicy;
 }
 export interface ConfigEnv {
     readonly FEISHU_APP_ID?: string;

package/dist/config.js

@@ -23,6 +23,15 @@ export const Config = z.object({
     logLevel: z.union([z.const('info'), z.const('debug')]).required(false),
     personaAutoSync: z.boolean().required(false),
     agentPreset: z.string().required(false),
+    approvalCard: z.boolean().required(false),
+    questionCard: z.boolean().required(false),
+    interactiveTimeoutMs: z.natural().min(1).required(false),
+    approvalPolicy: z.union([z.const('ask'), z.const('never')]).required(false),
+    reactions: z.boolean().required(false),
+    reactionOnStart: z.string().required(false),
+    reactionOnDone: z.string().required(false),
+    reactionOnFail: z.string().required(false),
+    gateRequireBotIdentity: z.boolean().required(false),
 });
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -36,6 +45,17 @@ export const DEFAULT_LOG_LEVEL = 'info';
 export const DEFAULT_PERSONA_AUTO_SYNC = true;
 /** Default agent preset for caduceus sessions. */
 export const DEFAULT_AGENT_PRESET = 'standard';
+/** Default message reactions. */
+export const DEFAULT_REACTIONS = true;
+export const DEFAULT_REACTION_ON_START = 'OnIt';
+export const DEFAULT_REACTION_ON_DONE = 'DONE';
+export const DEFAULT_REACTION_ON_FAIL = 'CROSS_MARK';
+/** Default session approval policy: ask, so dangerous actions prompt a card. */
+export const DEFAULT_APPROVAL_POLICY = 'ask';
+/** Default interactive-card switches/timeout. */
+export const DEFAULT_APPROVAL_CARD = true;
+export const DEFAULT_QUESTION_CARD = true;
+export const DEFAULT_INTERACTIVE_TIMEOUT_MS = 300_000;
 function firstNonEmpty(...values) {
     for (const value of values) {
         if (value !== undefined && value.length > 0)
@@ -61,6 +81,11 @@ export function resolveGatewayConfig(config = {}, env = process.env, cwd = proce
         busyMode: config.busyMode ?? DEFAULT_BUSY_MODE,
         groupSessionsPerUser: config.groupSessionsPerUser ?? DEFAULT_GROUP_SESSIONS_PER_USER,
         agentPreset: config.agentPreset ?? DEFAULT_AGENT_PRESET,
+        reactions: config.reactions ?? DEFAULT_REACTIONS,
+        reactionOnStart: config.reactionOnStart ?? DEFAULT_REACTION_ON_START,
+        reactionOnDone: config.reactionOnDone ?? DEFAULT_REACTION_ON_DONE,
+        reactionOnFail: config.reactionOnFail ?? DEFAULT_REACTION_ON_FAIL,
+        gateRequireBotIdentity: config.gateRequireBotIdentity ?? true,
     };
     return {
         ...(appId === undefined || appSecret === undefined ? {} : { credentials: { appId, appSecret } }),
@@ -68,5 +93,9 @@ export function resolveGatewayConfig(config = {}, env = process.env, cwd = proce
         logLevel: config.logLevel ?? DEFAULT_LOG_LEVEL,
         personaAutoSync: config.personaAutoSync ?? DEFAULT_PERSONA_AUTO_SYNC,
         agentPreset: config.agentPreset ?? DEFAULT_AGENT_PRESET,
+        approvalCard: config.approvalCard ?? DEFAULT_APPROVAL_CARD,
+        questionCard: config.questionCard ?? DEFAULT_QUESTION_CARD,
+        interactiveTimeoutMs: config.interactiveTimeoutMs ?? DEFAULT_INTERACTIVE_TIMEOUT_MS,
+        approvalPolicy: config.approvalPolicy ?? DEFAULT_APPROVAL_POLICY,
     };
 }

package/dist/gate.d.ts

@@ -17,7 +17,7 @@
 import type { LoggerLike } from './logger.js';
 import type { ChatType } from './transport/types.js';
 export type GateAcceptReason = 'p2p' | 'mentioned';
-export type GateDropReason = 'bot-sender' | 'not-allowed-chat' | 'not-allowed-user' | 'empty-text' | 'no-mention';
+export type GateDropReason = 'bot-sender' | 'not-allowed-chat' | 'not-allowed-user' | 'empty-text' | 'no-mention' | 'bot-identity-unknown';
 export type GateDecision = {
     readonly accept: true;
     readonly reason: GateAcceptReason;
@@ -35,6 +35,8 @@ export interface GateInput {
     readonly text: string;
     readonly mentions?: readonly string[];
     readonly botOpenId?: string;
+    /** Default true: fail closed when the bot's own open id is unknown. */
+    readonly requireBotIdentity?: boolean;
     readonly allowedChats: readonly string[];
     readonly allowedUsers: readonly string[];
 }

package/dist/gate.js

@@ -22,13 +22,14 @@ export function evaluateGate(input) {
     if (botOpenId !== undefined && botOpenId.length > 0) {
         if (mentions.includes(botOpenId))
             return { accept: true, reason: 'mentioned' };
+        return { accept: false, reason: 'no-mention' };
     }
-    else if (mentions.length > 0) {
-        // bot/v3/info unavailable: accept any mention rather than dropping every
-        // group message; the line still records the decision for diagnosis.
+    // Identity unknown: fail closed by default (never let an arbitrary @ through).
+    if (mentions.length === 0)
+        return { accept: false, reason: 'no-mention' };
+    if (input.requireBotIdentity === false)
         return { accept: true, reason: 'mentioned' };
-    }
-    return { accept: false, reason: 'no-mention' };
+    return { accept: false, reason: 'bot-identity-unknown' };
 }
 function prefix(value, length = 12) {
     const text = (value ?? '').slice(0, length);

package/dist/index.js

@@ -23,6 +23,7 @@ import { adaptLogger, teeLoggers } from './logger.js';
 import { formatStartupLine } from './observability.js';
 import { autoSyncPersona } from './persona/auto-sync.js';
 import { runPersonaCommand } from './persona/command.js';
+import { InteractiveRuntime } from './interactive/runtime.js';
 import { SelfChecker } from './selfcheck.js';
 import { hasSessionLog } from './session-files.js';
 import { SESSION_MAP_VERSION, SessionStore } from './session-key.js';
@@ -164,7 +165,21 @@ export function apply(ctx, config = {}) {
         logger,
     });
     const transport = new ReliableTransport(api, { logger });
-    const bridge = new Bridge({
+    let bridge;
+    const interactive = new InteractiveRuntime({
+        config: {
+            approvalCard: resolved.approvalCard,
+            questionCard: resolved.questionCard,
+            timeoutMs: resolved.interactiveTimeoutMs,
+        },
+        logger,
+        sendCard: (sessionId, card) => bridge.sendInteractiveCard(sessionId, card),
+        updateCard: (messageId, card) => transport.updateCard(messageId, card),
+    });
+    transport.onCardAction?.((action) => {
+        void interactive.handleCardAction(action);
+    });
+    bridge = new Bridge({
         transport,
         sessionMap,
         agents: makeAgents(ctx),
@@ -175,6 +190,10 @@ export function apply(ctx, config = {}) {
         // Lazy per use: the preset registry can register AFTER this plugin mounts.
         agentPresetsProvider: () => ctx.get('agentPresets'),
         selfCheck,
+        interactive,
+        rootCtx: ctx,
+        approvalProvider: () => ctx.get('approval'),
+        approvalPolicy: resolved.approvalPolicy,
         sessionPresetLookup: (sessionId) => ctx.get('sessions')?.get(sessionId)?.header
             ?.agentPreset,
         doctorInputs: (session) => {

package/dist/interactive/approval.d.ts

@@ -0,0 +1,9 @@
+import { type InteractiveContext, type InteractiveHost } from './types.js';
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+export interface ApprovalRequestLike {
+    readonly toolName: string;
+    readonly reason?: string;
+    readonly signal?: AbortSignal;
+}
+export type ApprovalAnswerer = (request: ApprovalRequestLike, next: () => Promise<ApprovalOutcome>) => Promise<ApprovalOutcome>;
+export declare function createApprovalAnswerer(host: InteractiveHost, contextFor: () => InteractiveContext | undefined): ApprovalAnswerer;