dsh-caduceus 0.1.0 → 0.4.1

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;

package/dist/interactive/approval.js

@@ -0,0 +1,85 @@
+/**
+ * `approval/request` answerer: send an approval card, wait for a button click
+ * (or timeout/abort), and return only closed dsh approval outcomes.
+ *
+ * Fail-closed rules:
+ * - approvalCard disabled / no owner context -> `unavailable` (never prompt);
+ * - card send fails -> log ERROR and `cancelled`;
+ * - timeout or abort -> `cancelled`;
+ * - callback handler resolves the pending entry with the chosen outcome.
+ *
+ * @module dsh-caduceus/interactive/approval
+ */
+import { approvalCard, approvalTerminalCard } from './cards.js';
+import { logPrefix } from './types.js';
+export function createApprovalAnswerer(host, contextFor) {
+    return async (request) => {
+        if (!host.config.approvalCard) {
+            host.logger.warn('interactive: approval skipped (approvalCard disabled)');
+            return 'unavailable';
+        }
+        const context = contextFor();
+        if (context === undefined) {
+            host.logger.warn('interactive: approval skipped (no session context)');
+            return 'unavailable';
+        }
+        let settle;
+        const outcome = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const entry = host.pending.add({
+            kind: 'approval',
+            scopeKey: context.scopeKey,
+            chatId: context.chatId,
+            ownerOpenId: context.ownerOpenId,
+            sessionId: context.sessionId,
+            createdAt: host.clock.now(),
+            resolve: (value) => settle(value),
+            reject: () => settle('cancelled'),
+            meta: { toolName: request.toolName, message: request.reason },
+        });
+        host.logger.info(`interactive: approval request id=${entry.id} questions=0 scope=${context.scopeKey}`);
+        const card = approvalCard(entry.id, context.sessionId, request.toolName, request.reason);
+        let timer;
+        const onAbort = () => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            void host
+                .updateCard(entry.cardMessageId ?? '', approvalTerminalCard(request.toolName, '已取消'))
+                .catch(() => undefined);
+            settle('cancelled');
+        };
+        const cleanup = () => {
+            if (timer !== undefined)
+                host.clock.clearTimeout(timer);
+            request.signal?.removeEventListener('abort', onAbort);
+        };
+        entry.cleanup = cleanup;
+        host.logger.info(`interactive: approval card sending chat=${logPrefix(context.chatId)}`);
+        try {
+            const sent = await host.sendCard(context.sessionId, card);
+            entry.cardMessageId = sent.messageId;
+            host.logger.info(`interactive: approval card sent messageId=${logPrefix(entry.cardMessageId)} thread=${logPrefix(sent.threadId ?? '-', 8)}`);
+        }
+        catch (error) {
+            host.pending.delete(entry.id);
+            host.logger.error(`interactive: approval card send failed: ${error instanceof Error ? error.message : String(error)}`);
+            return 'cancelled';
+        }
+        timer = host.clock.setTimeout(() => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            host.logger.info(`interactive: approval timed out after ${host.config.timeoutMs}ms`);
+            void host
+                .updateCard(entry.cardMessageId ?? '', approvalTerminalCard(request.toolName, '已过期'))
+                .catch(() => undefined);
+            settle('cancelled');
+        }, host.config.timeoutMs);
+        if (request.signal?.aborted === true) {
+            onAbort();
+            return outcome;
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true });
+        return outcome;
+    };
+}

package/dist/interactive/cards.d.ts

@@ -0,0 +1,36 @@
+import type { FeishuCard, FeishuCardElement } from '../transport/types.js';
+export interface CardButton {
+    readonly label: string;
+    readonly type?: 'primary' | 'danger' | 'default';
+    readonly value: Record<string, unknown>;
+}
+/** A card with optional buttons. */
+export declare function interactiveCard(title: string, lines: readonly string[], buttons?: readonly CardButton[], template?: string): FeishuCard;
+/** Card from pre-built elements (forms, inputs, action rows). */
+export declare function interactiveElementsCard(title: string, elements: readonly FeishuCardElement[], template?: string): FeishuCard;
+export declare function approvalCard(requestId: string, sessionId: string, toolName: string, reason: string | undefined): FeishuCard;
+export declare function approvalTerminalCard(toolName: string, outcome: string): FeishuCard;
+export interface QuestionCardInput {
+    readonly requestId: string;
+    readonly sessionId: string;
+    /** Extra warning appended to the card (e.g. the empty-custom hint). */
+    readonly hint?: string;
+    readonly questions: readonly {
+        readonly id: string;
+        readonly question: string;
+        readonly header?: string;
+        readonly detail?: string;
+        readonly options?: readonly {
+            readonly label: string;
+            readonly description?: string;
+        }[];
+        readonly multiSelect?: boolean;
+    }[];
+}
+export interface QuestionCardResult {
+    readonly card: FeishuCard;
+    readonly buttons: boolean;
+}
+/** Buttons only for exactly one single-select question with 1..4 options. */
+export declare function questionCard(input: QuestionCardInput): QuestionCardResult;
+export declare function questionTerminalCard(question: string, answer: string): FeishuCard;

package/dist/interactive/cards.js

@@ -0,0 +1,125 @@
+/**
+ * Interactive Feishu card builders (approval / question / terminal states).
+ *
+ * @module dsh-caduceus/interactive/cards
+ */
+import { buildCard } from '../render/cards.js';
+function div(content) {
+    return { tag: 'div', text: { tag: 'lark_md', content } };
+}
+function actionRow(buttons) {
+    return {
+        tag: 'action',
+        actions: buttons.map((button) => ({
+            tag: 'button',
+            text: { tag: 'plain_text', content: button.label },
+            type: button.type ?? 'default',
+            value: button.value,
+        })),
+    };
+}
+/** A card with optional buttons. */
+export function interactiveCard(title, lines, buttons = [], template = 'orange') {
+    const elements = lines.map(div);
+    if (buttons.length > 0)
+        elements.push(actionRow(buttons));
+    return buildCard({ title, template, elements });
+}
+/** Card from pre-built elements (forms, inputs, action rows). */
+export function interactiveElementsCard(title, elements, template = 'orange') {
+    return buildCard({ title, template, elements });
+}
+export function approvalCard(requestId, sessionId, toolName, reason) {
+    return interactiveCard(`审批请求 · ${toolName}`, [
+        reason === undefined || reason.trim().length === 0 ? '（无说明）' : reason,
+    ], [
+        {
+            label: '允许一次',
+            type: 'primary',
+            value: { kind: 'approval', id: requestId, sessionId, choice: 'allow' },
+        },
+        {
+            label: '拒绝',
+            type: 'danger',
+            value: { kind: 'approval', id: requestId, sessionId, choice: 'reject' },
+        },
+    ]);
+}
+export function approvalTerminalCard(toolName, outcome) {
+    return interactiveCard(`审批请求 · ${toolName}`, [outcome], [], 'grey');
+}
+/** Buttons only for exactly one single-select question with 1..4 options. */
+export function questionCard(input) {
+    const questions = input.questions;
+    const lines = [];
+    for (const question of questions) {
+        const heading = question.header === undefined ? question.question : `${question.header}：${question.question}`;
+        lines.push(`**${heading}**`);
+        if (question.detail !== undefined && question.detail.trim().length > 0)
+            lines.push(question.detail);
+        if (question.multiSelect === true)
+            lines.push('_（多选暂不支持，仅能选一项）_');
+        for (const option of question.options ?? []) {
+            lines.push(`- ${option.label}${option.description === undefined ? '' : ` — ${option.description}`}`);
+        }
+    }
+    if (input.hint !== undefined && input.hint.length > 0)
+        lines.push(`**${input.hint}**`);
+    const only = questions.length === 1 ? questions[0] : undefined;
+    const options = only?.options ?? [];
+    const buttons = only !== undefined &&
+        options.length > 0 &&
+        options.length <= 4;
+    const elements = lines.map(div);
+    if (buttons) {
+        elements.push(actionRow(options.map((option) => ({
+            label: option.label,
+            value: {
+                kind: 'question',
+                id: input.requestId,
+                sessionId: input.sessionId,
+                questionId: only.id,
+                label: option.label,
+            },
+        }))));
+    }
+    if (only === undefined) {
+        lines.push('_本版暂不支持在卡片内输入文字，请直接回复文本作答。_');
+        return { card: interactiveCard('问题', lines), buttons: false };
+    }
+    elements.push(div('或自己填：'));
+    elements.push({
+        tag: 'form',
+        name: 'question_form',
+        elements: [
+            {
+                tag: 'input',
+                name: 'other',
+                placeholder: { tag: 'plain_text', content: '输入自定义答案' },
+                max_length: 200,
+            },
+            {
+                tag: 'button',
+                name: 'submit',
+                type: 'primary',
+                action_type: 'form_submit',
+                text: { tag: 'plain_text', content: '提交' },
+                value: {
+                    kind: 'question',
+                    id: input.requestId,
+                    sessionId: input.sessionId,
+                    questionId: only.id,
+                    form: true,
+                },
+            },
+        ],
+    });
+    const title = only.header === undefined ? `问题 · ${only.question}` : `问题 · ${only.header}`;
+    return {
+        card: interactiveElementsCard(title, elements),
+        buttons,
+    };
+}
+export function questionTerminalCard(question, answer) {
+    return interactiveCard(`问题 · ${question}`, [answer], [], 'grey');
+}

package/dist/interactive/pending.d.ts

@@ -0,0 +1,29 @@
+export type PendingKind = 'approval' | 'question';
+export interface PendingEntry {
+    readonly id: string;
+    readonly kind: PendingKind;
+    readonly scopeKey: string;
+    readonly chatId: string;
+    readonly ownerOpenId: string;
+    readonly sessionId: string;
+    readonly createdAt: number;
+    readonly resolve: (value: unknown) => void;
+    readonly reject: (error: unknown) => void;
+    /** Card message id assigned after a successful send. */
+    cardMessageId?: string;
+    /** Extra presentation data (tool name / questions). */
+    readonly meta?: Record<string, unknown>;
+    /** Clears timers/signal listeners when the runtime settles the entry. */
+    cleanup?: () => void;
+}
+export type NewPendingEntry = Omit<PendingEntry, 'id'> & {
+    readonly id?: string;
+};
+export declare class PendingRegistry {
+    #private;
+    add(entry: NewPendingEntry): PendingEntry;
+    get(id: string): PendingEntry | undefined;
+    delete(id: string): PendingEntry | undefined;
+    get size(): number;
+    clear(): void;
+}

package/dist/interactive/pending.js

@@ -0,0 +1,39 @@
+/**
+ * In-memory pending interactive requests (one per approval/question card).
+ *
+ * Entries are keyed by a random id embedded in every button value. They carry
+ * the scope owner so a click from anyone else can be ignored. The registry is
+ * intentionally dumb: the runtime decides when an entry settles, patches the
+ * card, and clears timers through `cleanup`.
+ *
+ * @module dsh-caduceus/interactive/pending
+ */
+import { randomUUID } from 'node:crypto';
+export class PendingRegistry {
+    #entries = new Map();
+    add(entry) {
+        const id = entry.id ?? randomUUID();
+        const value = { ...entry, id };
+        this.#entries.set(id, value);
+        return value;
+    }
+    get(id) {
+        return this.#entries.get(id);
+    }
+    delete(id) {
+        const value = this.#entries.get(id);
+        if (value === undefined)
+            return undefined;
+        this.#entries.delete(id);
+        value.cleanup?.();
+        return value;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    clear() {
+        for (const entry of this.#entries.values())
+            entry.cleanup?.();
+        this.#entries.clear();
+    }
+}

package/dist/interactive/question.d.ts

@@ -0,0 +1,25 @@
+import { type InteractiveContext, type InteractiveHost } from './types.js';
+export interface QuestionItemLike {
+    readonly id: string;
+    readonly question: string;
+    readonly header?: string;
+    readonly detail?: string;
+    readonly options?: readonly {
+        readonly label: string;
+        readonly description?: string;
+    }[];
+    readonly multiSelect?: boolean;
+}
+export interface QuestionRequestLike {
+    readonly questions: readonly QuestionItemLike[];
+    readonly signal?: AbortSignal;
+}
+export interface QuestionAnswerLike {
+    readonly answers: readonly {
+        readonly id: string;
+        readonly selected: readonly string[];
+        readonly custom?: string;
+    }[];
+}
+export type QuestionAnswerer = (request: QuestionRequestLike, next: () => Promise<QuestionAnswerLike>) => Promise<QuestionAnswerLike>;
+export declare function createQuestionAnswerer(host: InteractiveHost, contextFor: () => InteractiveContext | undefined): QuestionAnswerer;