dsh-caduceus 0.1.1 → 0.4.1

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;

package/dist/interactive/question.js

@@ -0,0 +1,86 @@
+/**
+ * `user-questions/request` answerer: render one question card (buttons when a
+ * single question has 1..4 options) and resolve the first click. Free-text
+ * answers are not implemented in this version; text-only cards expire.
+ *
+ * @module dsh-caduceus/interactive/question
+ */
+import { questionCard, questionTerminalCard } from './cards.js';
+import { logPrefix } from './types.js';
+export function createQuestionAnswerer(host, contextFor) {
+    return async (request) => {
+        if (!host.config.questionCard) {
+            host.logger.warn('interactive: question skipped (questionCard disabled)');
+            throw new Error('interactive question cards are disabled');
+        }
+        const context = contextFor();
+        if (context === undefined) {
+            host.logger.warn('interactive: question skipped (no session context)');
+            throw new Error('no caduceus session context for user question');
+        }
+        let settle;
+        let fail;
+        const answer = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        const entry = host.pending.add({
+            kind: 'question',
+            scopeKey: context.scopeKey,
+            chatId: context.chatId,
+            ownerOpenId: context.ownerOpenId,
+            sessionId: context.sessionId,
+            createdAt: host.clock.now(),
+            resolve: (value) => settle(value),
+            reject: (error) => fail(error),
+            meta: { questions: request.questions },
+        });
+        host.logger.info(`interactive: question request id=${entry.id} questions=${request.questions.length} scope=${context.scopeKey}`);
+        const rendered = questionCard({
+            requestId: entry.id,
+            sessionId: context.sessionId,
+            questions: request.questions,
+        });
+        let timer;
+        const onAbort = () => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            void host
+                .updateCard(entry.cardMessageId ?? '', questionTerminalCard(request.questions[0]?.question ?? '问题', '已取消'))
+                .catch(() => undefined);
+            fail(new Error('user question cancelled'));
+        };
+        const cleanup = () => {
+            if (timer !== undefined)
+                host.clock.clearTimeout(timer);
+            request.signal?.removeEventListener('abort', onAbort);
+        };
+        entry.cleanup = cleanup;
+        host.logger.info(`interactive: question card sending chat=${logPrefix(context.chatId)}`);
+        try {
+            const sent = await host.sendCard(context.sessionId, rendered.card);
+            entry.cardMessageId = sent.messageId;
+            host.logger.info(`interactive: question card sent messageId=${logPrefix(entry.cardMessageId)} thread=${logPrefix(sent.threadId ?? '-', 8)}`);
+        }
+        catch (error) {
+            host.pending.delete(entry.id);
+            host.logger.error(`interactive: question card send failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        timer = host.clock.setTimeout(() => {
+            if (host.pending.delete(entry.id) === undefined)
+                return;
+            host.logger.info(`interactive: question timed out after ${host.config.timeoutMs}ms`);
+            void host
+                .updateCard(entry.cardMessageId ?? '', questionTerminalCard(request.questions[0]?.question ?? '问题', '已过期'))
+                .catch(() => undefined);
+            fail(new Error('user question timed out'));
+        }, host.config.timeoutMs);
+        if (request.signal?.aborted === true) {
+            onAbort();
+            return answer;
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true });
+        return answer;
+    };
+}

package/dist/interactive/runtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime that owns the pending registry, sends/patch cards, routes
+ * `card.action.trigger` clicks, and installs the two agent-scoped answerers.
+ *
+ * @module dsh-caduceus/interactive/runtime
+ */
+import type { LoggerLike } from '../logger.js';
+import { type Clock } from '../render/stream.js';
+import type { CardAction, InteractiveConfig, InteractiveContext } from './types.js';
+import { PendingRegistry } from './pending.js';
+import type { FeishuCard } from '../transport/types.js';
+export interface InteractiveRuntimeOptions {
+    readonly config: InteractiveConfig;
+    readonly logger?: LoggerLike;
+    readonly clock?: Clock;
+    sendCard(sessionId: string, card: FeishuCard): Promise<{
+        readonly messageId: string;
+        readonly threadId?: string;
+    }>;
+    updateCard(messageId: string, card: FeishuCard): Promise<void>;
+}
+export declare class InteractiveRuntime {
+    #private;
+    readonly config: InteractiveConfig;
+    readonly logger: LoggerLike;
+    readonly clock: Clock;
+    readonly pending: PendingRegistry;
+    constructor(options: InteractiveRuntimeOptions);
+    /**
+     * Register both waterfall answerers ONCE on the plugin root context, as dsh's
+     * own ACP bridge does. Ownership is decided per request from
+     * `request.agent.session.id`; requests for other agents are delegated by
+     * calling `next()`, never claimed.
+     */
+    registerRoot(rootCtx: unknown, resolve: {
+        ownsSession(sessionId: string): boolean;
+        contextFor(sessionId: string): InteractiveContext | undefined;
+    }): boolean;
+    /**
+     * Route one card click. Unknown ids are ignored; non-owners are ignored with
+     * a warning and do not resolve or patch anything.
+     */
+    handleCardAction(action: CardAction): Promise<void>;
+}

package/dist/interactive/runtime.js

@@ -0,0 +1,147 @@
+import { silentLogger } from '../logger.js';
+import { systemClock } from '../render/stream.js';
+import { describeScope, isEventScope, logPrefix } from './types.js';
+import { createApprovalAnswerer } from './approval.js';
+import { PendingRegistry } from './pending.js';
+import { createQuestionAnswerer } from './question.js';
+import { approvalTerminalCard, questionCard, questionTerminalCard } from './cards.js';
+export class InteractiveRuntime {
+    config;
+    logger;
+    clock;
+    pending = new PendingRegistry();
+    #sendCard;
+    #updateCard;
+    constructor(options) {
+        this.config = options.config;
+        this.logger = options.logger ?? silentLogger();
+        this.clock = options.clock ?? systemClock;
+        this.#sendCard = options.sendCard;
+        this.#updateCard = options.updateCard;
+    }
+    /**
+     * Register both waterfall answerers ONCE on the plugin root context, as dsh's
+     * own ACP bridge does. Ownership is decided per request from
+     * `request.agent.session.id`; requests for other agents are delegated by
+     * calling `next()`, never claimed.
+     */
+    registerRoot(rootCtx, resolve) {
+        if (!isEventScope(rootCtx)) {
+            this.logger.warn(`interactive: register skipped (not an event scope: ${describeScope(rootCtx)})`);
+            return false;
+        }
+        rootCtx.on('approval/request', async (request, next) => {
+            const sessionId = sessionIdOf(request);
+            if (sessionId === undefined || !resolve.ownsSession(sessionId)) {
+                this.logger.info(`interactive: approval request agent=${sessionId === undefined ? '?' : logPrefix(sessionId)} not ours, delegated`);
+                return next();
+            }
+            this.logger.info(`interactive: approval request agent=${logPrefix(sessionId)} claimed`);
+            const context = resolve.contextFor(sessionId);
+            return createApprovalAnswerer(this.#host(), () => context)(request, next);
+        });
+        rootCtx.on('user-questions/request', async (request, next) => {
+            const sessionId = sessionIdOf(request);
+            if (sessionId === undefined || !resolve.ownsSession(sessionId)) {
+                this.logger.info(`interactive: question request agent=${sessionId === undefined ? '?' : logPrefix(sessionId)} not ours, delegated`);
+                return next();
+            }
+            this.logger.info(`interactive: question request agent=${logPrefix(sessionId)} claimed`);
+            const context = resolve.contextFor(sessionId);
+            return createQuestionAnswerer(this.#host(), () => context)(request, next);
+        });
+        this.logger.info('interactive: answerers registered (root scope)');
+        return true;
+    }
+    /**
+     * Route one card click. Unknown ids are ignored; non-owners are ignored with
+     * a warning and do not resolve or patch anything.
+     */
+    async handleCardAction(action) {
+        const id = typeof action.value['id'] === 'string' ? action.value['id'] : undefined;
+        if (id === undefined) {
+            this.logger.info('card action ignored (unknown id)');
+            return;
+        }
+        this.logger.info(`card action id=${id} kind=${String(action.value['kind'] ?? '?')} operator=${logPrefix(action.operatorOpenId)}`);
+        const entry = this.pending.get(id);
+        if (entry === undefined) {
+            this.logger.info('card action ignored (unknown id)');
+            return;
+        }
+        if (action.operatorOpenId !== entry.ownerOpenId) {
+            this.logger.warn(`ignored card action from non-owner ${action.operatorOpenId} for ${entry.kind} ${id}`);
+            return;
+        }
+        if (entry.kind === 'question' && (action.formValue !== undefined || action.value['form'] === true)) {
+            const questions = entry.meta?.['questions'];
+            const question = questions?.[0]?.question ?? '问题';
+            const questionId = typeof action.value['questionId'] === 'string'
+                ? action.value['questionId']
+                : (questions?.[0]?.id ?? '');
+            const custom = (action.formValue?.['other'] ?? '').trim();
+            if (custom.length === 0) {
+                // Keep the pending entry and its timer: prompt again on the same card.
+                const rebuilt = questionCard({
+                    requestId: entry.id,
+                    sessionId: entry.sessionId,
+                    ...(questions === undefined ? { questions: [] } : { questions }),
+                    hint: '请填写后再提交',
+                });
+                await this.#patchTerminal(entry, rebuilt.card);
+                return;
+            }
+            this.pending.delete(id);
+            await this.#patchTerminal(entry, questionTerminalCard(question, `已填写：${custom.slice(0, 40)}`));
+            entry.resolve({ answers: [{ id: questionId, selected: [], custom }] });
+            return;
+        }
+        this.pending.delete(id);
+        if (entry.kind === 'approval') {
+            const choice = action.value['choice'] === 'allow' ? 'allow' : 'reject';
+            const outcome = choice === 'allow' ? 'allowed-once' : 'rejected';
+            await this.#patchTerminal(entry, approvalTerminalCard(String(entry.meta?.['toolName'] ?? 'tool'), outcome === 'allowed-once' ? '已允许' : '已拒绝'));
+            entry.resolve(outcome);
+            return;
+        }
+        const label = typeof action.value['label'] === 'string' ? action.value['label'] : '';
+        const questionId = typeof action.value['questionId'] === 'string' ? action.value['questionId'] : '';
+        const question = entry.meta?.['questions']?.[0]
+            ?.question ?? '问题';
+        await this.#patchTerminal(entry, questionTerminalCard(question, `已选择：${label}`));
+        entry.resolve({ answers: [{ id: questionId, selected: [label] }] });
+    }
+    async #patchTerminal(entry, card) {
+        if (entry.cardMessageId === undefined)
+            return;
+        try {
+            await this.#updateCard(entry.cardMessageId, card);
+        }
+        catch (error) {
+            this.logger.warn(`interactive card patch failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    #host() {
+        return {
+            config: this.config,
+            logger: this.logger,
+            clock: this.clock,
+            pending: this.pending,
+            sendCard: (sessionId, card) => this.#sendCard(sessionId, card),
+            updateCard: (messageId, card) => this.#updateCard(messageId, card),
+        };
+    }
+}
+/** Extract `request.agent.session.id` structurally (dsh waterfall payloads). */
+function sessionIdOf(request) {
+    if (typeof request !== 'object' || request === null)
+        return undefined;
+    const agent = request.agent;
+    if (typeof agent !== 'object' || agent === null)
+        return undefined;
+    const session = agent.session;
+    if (typeof session !== 'object' || session === null)
+        return undefined;
+    const id = session.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/dist/interactive/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared seams for caduceus interactive cards (approval + user questions).
+ *
+ * The dsh services and the Cordis waterfall are adapted structurally so unit
+ * tests never import dsh internals; the gateway wires the real transport and
+ * agent scope at the edge.
+ *
+ * @module dsh-caduceus/interactive/types
+ */
+import type { LoggerLike } from '../logger.js';
+import type { Clock } from '../render/stream.js';
+import type { CardAction, FeishuCard } from '../transport/types.js';
+export type { CardAction };
+import type { PendingRegistry } from './pending.js';
+export interface InteractiveConfig {
+    /** Send approval cards (default true). */
+    readonly approvalCard: boolean;
+    /** Send question cards (default true). */
+    readonly questionCard: boolean;
+    /** How long a card waits before it expires (ms, default 300000). */
+    readonly timeoutMs: number;
+}
+/** Where the card belongs and who may click it. */
+export interface InteractiveContext {
+    readonly scopeKey: string;
+    readonly chatId: string;
+    readonly ownerOpenId: string;
+    readonly sessionId: string;
+}
+/** A Cordis context (the plugin root or an agent scope); only `on` is needed. */
+export interface EventScopeLike {
+    on(name: string, listener: (...args: any[]) => any): unknown;
+}
+export declare function logPrefix(value: string, max?: number): string;
+/** Short, safe description of a value for the attach-skipped diagnostic. */
+export declare function describeScope(value: unknown): string;
+export declare function isEventScope(value: unknown): value is EventScopeLike;
+/** What the approval/question answerers need from the runtime. */
+export interface InteractiveHost {
+    readonly config: InteractiveConfig;
+    readonly logger: LoggerLike;
+    readonly clock: Clock;
+    readonly pending: PendingRegistry;
+    sendCard(sessionId: string, card: FeishuCard): Promise<{
+        readonly messageId: string;
+        readonly threadId?: string;
+    }>;
+    updateCard(messageId: string, card: FeishuCard): Promise<void>;
+}
+/** CardAction is defined by the transport seam. */