@xmanrui/dsh-im 4.35.1 → 4.36.1

package/plugin-src/host/modern-harness-api.mjs

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 
-import { hasActiveHarnessInteractionOwner } from '../../src/channels/shared/harness-client.mjs';
+import { activeHarnessInteractionOwner, hasActiveHarnessInteractionOwner, harnessToolCallFromEvent, HarnessInteractionError } from '../../src/channels/shared/harness-client.mjs';
 import { extractConnectionEvidence } from '../../src/channels/shared/connection-error.mjs';
 
 const modernApis = new WeakMap();
@@ -196,6 +196,7 @@ class MuxSubscription {
 
 class ModernHarnessApi {
   #gateway;
+  #deliveryService;
   #scope;
   #mux = new Set();
   #pendingQuestions = new Map();
@@ -286,6 +287,10 @@ class ModernHarnessApi {
     }
   }
 
+  setDeliveryService(service) {
+    if (service) this.#deliveryService = service;
+  }
+
   async #invoke(namespace, method, args, signal) {
     return this.#gateway.invoke(remoteRequest(namespace, method, args, signal));
   }
@@ -467,7 +472,9 @@ class ModernHarnessApi {
     subscription = new MuxSubscription(signal, () => this.#mux.delete(subscription));
     this.#mux.add(subscription);
     for (const pending of this.#pendingQuestions.values()) subscription.push(this.#questionFrame(pending));
-    for (const pending of this.#pendingApprovals.values()) subscription.push(this.#approvalFrame(pending));
+    for (const pending of this.#pendingApprovals.values()) {
+      if (pending.broadcast !== false && pending.imAvailable !== false) subscription.push(this.#approvalFrame(pending));
+    }
     return subscription;
   }
 
@@ -630,6 +637,7 @@ class ModernHarnessApi {
         type: 'approval/requested',
         sessionId: pending.sessionId,
         approvalId: pending.approvalId,
+        ...(pending.competitive ? { competitive: true } : {}),
         toolName: pending.toolName,
         ...(pending.callId === undefined ? {} : { callId: pending.callId }),
         ...(pending.reason === undefined ? {} : { reason: pending.reason }),
@@ -638,6 +646,123 @@ class ModernHarnessApi {
   }
 
   #requestApproval(request, next) {
+    const session = request?.agent?.session;
+    const sessionId = session?.id ?? request?.agent?.id;
+    const events = sessionEvents(session);
+    if (typeof sessionId !== 'string' || !events) return next();
+    const owner = activeHarnessInteractionOwner(this.#scope, sessionId, events);
+    if (owner && !owner.competitiveApprovals) return this.#requestExclusiveApproval(request, next);
+    if (!owner && typeof this.#deliveryService?.presentSessionSyncApproval !== 'function') return next();
+    const turnSignal = request.signal;
+    if (turnSignal?.aborted) return Promise.resolve('cancelled');
+    const claimed = new Set([...this.#pendingApprovals.values()].map((entry) => entry.approvalId));
+    const decided = new Set();
+    let approvalId;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event.type === 'approval/decided') decided.add(event.data?.id);
+      if (event.type !== 'approval/asked') continue;
+      const id = event.data?.id;
+      if (!id || decided.has(id) || claimed.has(id)
+        || (request.callId ?? null) !== (event.data?.callId ?? null)) continue;
+      approvalId = id;
+      break;
+    }
+    if (!approvalId) return next();
+    let toolCall = owner?.toolCalls.get(request.callId);
+    if (!toolCall) {
+      for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === 'turn/start') break;
+        const call = harnessToolCallFromEvent(event);
+        if (call?.callId === request.callId && call.name === request.toolName) {
+          toolCall = call;
+          break;
+        }
+      }
+    }
+    // This controller retires only this approval; the caller keeps its turn signal.
+    const lifetime = new AbortController();
+    request.signal = lifetime.signal;
+    let nativeAvailable = true;
+    let resolveResult;
+    const result = new Promise((resolve) => { resolveResult = resolve; });
+    const pending = {
+      rpcId: randomUUID(), sessionId, approvalId,
+      toolName: request.toolName, callId: request.callId, reason: request.reason,
+      competitive: true, broadcast: Boolean(owner), imAvailable: true,
+      settle: (outcome) => {
+        if (!this.#pendingApprovals.delete(pending.rpcId)) return false;
+        turnSignal?.removeEventListener('abort', onAbort);
+        if (pending.broadcast) this.#broadcast({
+          type: 'approval/resolved', sessionId, approvalId, outcome,
+        });
+        // Reserve the result before aborting the losing native presentation.
+        resolveResult(outcome);
+        lifetime.abort(new Error('approval settled'));
+        if (request.signal === lifetime.signal) request.signal = turnSignal;
+        return true;
+      },
+      withdraw: () => {
+        if (!this.#pendingApprovals.has(pending.rpcId) || !pending.imAvailable) return false;
+        pending.imAvailable = false;
+        if (pending.broadcast) this.#broadcast({
+          type: 'approval/resolved', sessionId, approvalId, outcome: 'unavailable',
+        });
+        if (!nativeAvailable) pending.settle('unavailable');
+        return true;
+      },
+    };
+    const onAbort = () => pending.settle('cancelled');
+    this.#pendingApprovals.set(pending.rpcId, pending);
+    turnSignal?.addEventListener('abort', onAbort, { once: true });
+    if (turnSignal?.aborted) onAbort();
+    // Start both providers without waiting for target lookup or platform delivery.
+    Promise.resolve().then(() => {
+      if (lifetime.signal.aborted) return 'cancelled';
+      return next();
+    }).then((outcome) => {
+      if (outcome === 'allowed-once' || outcome === 'rejected') pending.settle(outcome);
+      else {
+        nativeAvailable = false;
+        if (!pending.imAvailable) pending.settle('unavailable');
+      }
+    }, (error) => {
+      nativeAvailable = false;
+      if (!lifetime.signal.aborted) console.warn('[dsh-im] native approval provider unavailable:', error?.code ?? error?.name);
+      if (!pending.imAvailable) pending.settle('unavailable');
+    });
+    if (!lifetime.signal.aborted && owner) {
+      this.#broadcast(this.#approvalFrame(pending).payload, pending.rpcId);
+    } else if (!lifetime.signal.aborted) {
+      const respond = async (response) => {
+        const receipt = this.#respond({ rpcId: pending.rpcId, result: response });
+        if (!receipt.accepted) throw new HarnessInteractionError(
+          `interaction-${receipt.reason}`, 'This approval is no longer answerable',
+        );
+        return receipt;
+      };
+      const interaction = {
+        kind: 'approval', interactionId: approvalId, rpcId: pending.rpcId, sessionId,
+        payload: this.#approvalFrame(pending).payload, toolCall, respond,
+        withdraw: async () => pending.withdraw(),
+      };
+      Promise.resolve().then(() => {
+        if (lifetime.signal.aborted) return false;
+        return this.#deliveryService.presentSessionSyncApproval(sessionId, interaction, {
+          signal: lifetime.signal, completion: result,
+        });
+      }).then((available) => {
+        if (!available) pending.withdraw();
+      }, (error) => {
+        if (!lifetime.signal.aborted) console.warn('[dsh-im] synced approval delivery unavailable:', error?.code ?? error?.name);
+        pending.withdraw();
+      });
+    }
+    return result;
+  }
+
+  #requestExclusiveApproval(request, next) {
     const owner = this.#claimableAgent(request?.agent);
     if (!owner) return next();
     if (request.signal?.aborted) return Promise.resolve('cancelled');
@@ -687,6 +812,12 @@ class ModernHarnessApi {
   #respond(message) {
     const approval = this.#pendingApprovals.get(message?.rpcId);
     if (approval) {
+      if (approval.imAvailable === false) return { accepted: false, reason: 'not-pending' };
+      if (approval.competitive && message?.result?.ok === false
+        && message?.result?.error?.code === 'unavailable') {
+        return approval.withdraw()
+          ? { accepted: true } : { accepted: false, reason: 'not-pending' };
+      }
       const value = message?.result?.value;
       if (message?.result?.ok !== true
         || !value || typeof value !== 'object'
@@ -738,18 +869,22 @@ class ModernHarnessApi {
 }
 
 /** Create one modern compatibility API per Cordis Host root. */
-export function modernHarnessApi(ctx) {
+export function modernHarnessApi(ctx, { deliveryService } = {}) {
   const scope = ctx?.root ?? ctx;
   if (!scope || !['object', 'function'].includes(typeof scope)) {
     throw new TypeError('dsh-im requires a Cordis Host context');
   }
   const cached = modernApis.get(scope);
-  if (cached) return cached;
+  if (cached) {
+    cached.setDeliveryService(deliveryService);
+    return cached;
+  }
   const gateway = ctx?.typertGateway;
   if (!gateway || typeof gateway.invoke !== 'function' || typeof gateway.stream !== 'function') {
     throw new TypeError('dsh-im requires the modern Host Typert gateway');
   }
   const api = new ModernHarnessApi(ctx, gateway, scope);
+  api.setDeliveryService(deliveryService);
   modernApis.set(scope, api);
   if (typeof ctx.effect === 'function') {
     ctx.effect(() => () => {

package/src/channels/dingtalk/dingtalk-bridge.mjs

@@ -1647,6 +1647,12 @@ export class DingtalkHarnessBridge {
     }
   }
 
+  async presentSessionSyncApproval(interaction, context, options = {}) {
+    return this.#approvals.handleSessionSyncRequested(interaction, context, {
+      ...options, runtimeSignal: this.#signal, accessPolicy: this.#accessPolicy,
+    });
+  }
+
   async #handleInteraction(interaction, {
     key,
     actor,

package/src/channels/dingtalk/dingtalk-controller.mjs

@@ -442,6 +442,20 @@ export class DingtalkController {
     });
   }
 
+  async presentSessionSyncApproval(botId, target, interaction, options = {}) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown DingTalk bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.presentSessionSyncApproval !== 'function') {
+        const error = new Error(t('钉钉消息连接当前离线'));
+        error.code = 'bot-not-connected';
+        throw error;
+      }
+      return runtime.presentSessionSyncApproval(target, interaction, options);
+    });
+  }
+
   /** Removes one bot, its secret, runtime, and local conversation state. */
   async deleteBot(botId) {
     const warnings = [];

package/src/channels/dingtalk/dingtalk-runtime.mjs

@@ -432,6 +432,16 @@ export class DingtalkRuntime {
     });
   }
 
+  async presentSessionSyncApproval(target, interaction, options = {}) {
+    if (!this.#status.ready || !this.#bridge) return false;
+    const actor = typeof target?.route?.userId === 'string' ? target.route.userId.trim() : '';
+    if (!actor) return false;
+    return this.#bridge.presentSessionSyncApproval(interaction, {
+      key: options.key, actor, validate: options.validate,
+      send: (text) => this.sendProactiveText(target, text),
+    }, options);
+  }
+
   async sendProactiveText(target, text, { signal } = {}) {
     const userId = typeof target?.route?.userId === 'string'
       ? target.route.userId.trim() : '';

package/src/channels/discord/discord-runtime.mjs

@@ -605,6 +605,19 @@ export class DiscordRuntime {
     return this.#bridge.sendConnectionTest(text);
   }
 
+  async presentSessionSyncApproval(target, interaction, options = {}) {
+    if (!this.#status.ready || !this.#bridge) return false;
+    const channelId = target?.route?.channelId;
+    const channel = await this.#api.getChannel({ channelId, signal: options.signal });
+    const actor = channel?.type === 1 && channel.recipients?.length === 1
+      ? channel.recipients[0]?.id : '';
+    if (!actor) return false;
+    return this.#bridge.presentSessionSyncApproval(interaction, {
+      key: options.key, actor, validate: options.validate,
+      send: (text) => this.sendProactiveText(target, text),
+    }, options);
+  }
+
   async sendProactiveText(target, text, options = {}) {
     if (!this.#status.ready || !this.#bridge) {
       const error = new Error('Discord bot is not connected');

package/src/channels/feishu/bridge.mjs

@@ -3161,6 +3161,7 @@ export class FeishuHarnessBridge {
       }
       const sentId = nonEmptyString(response?.data?.message_id);
       if (!sentId) throw new Error('Feishu card send returned no message_id');
+      this.#rememberCardRoute(sentId, response?.data?.chat_id ?? chatId, options);
       return sentId;
     }
 
@@ -6043,20 +6044,16 @@ export class FeishuHarnessBridge {
     }
   }
 
-  async #handleInteraction(interaction, {
-    key,
-    actor,
-    chatId,
-    requiresMention,
-    replyToMessageId,
-  }) {
+  #approvalContext({ key, actor, chatId, requiresMention, replyToMessageId, receiveIdType,
+    validate, send = (text) => this.#send(chatId, text, { replyTo: replyToMessageId }) }) {
     let approvalCardMessageId = null;
     let approvalCardData = null;
-    if (await this.#approvals.handleRequested(interaction, {
+    return {
       key,
       actor,
       requiresMention,
-      send: (text) => this.#send(chatId, text, { replyTo: replyToMessageId }),
+      send,
+      validate,
       // Approvals render as interactive cards with approve/reject buttons by
       // default. Set the bridge `interactionCards` option (or
       // DSH_IM_INTERACTION_CARDS=0) to keep the plain-text reply flow.
@@ -6073,27 +6070,47 @@ export class FeishuHarnessBridge {
               approvalCardMessageId = await this.#sendCard(
                 chatId,
                 approvalCard(approvalCardData),
-                { key, replyTo: replyToMessageId },
+                { key, replyTo: replyToMessageId, receiveIdType },
               ).catch(async () => {
                 // Fall back to the plain-text approval if the card cannot be
                 // sent. If the text send also fails, let the error propagate so
                 // the pending approval is not marked as presented and the
                 // existing retry/reconnect logic can run.
-                await this.#send(chatId, pending.text, { replyTo: replyToMessageId });
+                await send(pending.text);
                 return null;
               });
             },
             onResolved: async (resolvedText) => {
               if (!approvalCardMessageId) return;
-              await this.#patchCardMessage(
+              const patched = await this.#patchCardMessage(
                 chatId,
                 approvalCardMessageId,
                 approvalCard({ ...approvalCardData, resolvedText }),
               );
+              if (!patched) throw new Error('Approval card update failed');
             },
           }
         : {}),
-    })) return;
+    };
+
+  }
+
+  async presentSessionSyncApproval(interaction, context, options = {}) {
+    return this.#approvals.handleSessionSyncRequested(interaction, this.#approvalContext(context), {
+      ...options, runtimeSignal: this.#signal, accessPolicy: this.#accessPolicy,
+    });
+  }
+
+  async #handleInteraction(interaction, {
+    key,
+    actor,
+    chatId,
+    requiresMention,
+    replyToMessageId,
+  }) {
+    if (await this.#approvals.handleRequested(interaction, this.#approvalContext({
+      key, actor, chatId, requiresMention, replyToMessageId,
+    }))) return;
 
     // Approval requests return above; the existing question state machine stays unchanged.
     if (interaction?.kind !== 'question') return;

package/src/channels/feishu/external-consumer.mjs

@@ -0,0 +1,118 @@
+function refusal(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function identifier(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 512 ? value : undefined;
+}
+
+export function normalizeExternalText(event, { botId, appId, botOpenId, fingerprint }) {
+  const message = event?.message;
+  const actorId = identifier(event?.sender?.sender_id?.open_id);
+  const messageId = identifier(message?.message_id);
+  const conversationId = identifier(message?.chat_id);
+  const eventId = identifier(event?.event_id ?? event?.header?.event_id);
+  const eventApp = event?.app_id ?? event?.header?.app_id;
+  if (eventApp !== undefined && eventApp !== appId) throw refusal('account-changed');
+  if (event?.sender?.sender_type === 'app' || event?.sender?.sender_type === 'bot') return null;
+  if (event?.sender?.sender_type !== 'user'
+    || !['p2p', 'group'].includes(message?.chat_type) || message?.message_type !== 'text') return null;
+  if (message.chat_type === 'group' && !identifier(botOpenId)) throw refusal('account-unverified');
+  if (message.mentions !== undefined && (!Array.isArray(message.mentions) || message.mentions.length > 100))
+    throw refusal('invalid-inbound');
+  const mentions = Object.freeze((message.mentions ?? []).map(mention => {
+    const id = identifier(mention?.id?.open_id ?? mention?.open_id);
+    const key = identifier(mention?.key);
+    if (!id || !key) throw refusal('invalid-inbound');
+    return Object.freeze({ id, key, ...(identifier(mention.name) ? { name: mention.name } : {}) });
+  }));
+  if (!actorId || !messageId || !conversationId || !eventId
+    || !/^[a-f0-9]{64}$/.test(fingerprint ?? '')) throw refusal('invalid-inbound');
+  let text;
+  try { text = JSON.parse(message.content)?.text; } catch { throw refusal('invalid-inbound'); }
+  if (typeof text !== 'string' || !text.trim() || text.length > 16000) throw refusal('invalid-inbound');
+  const milliseconds = Number(message.create_time);
+  const timestamp = new Date(milliseconds);
+  if (!Number.isFinite(milliseconds) || milliseconds <= 0 || !Number.isFinite(timestamp.getTime()))
+    throw refusal('invalid-inbound');
+  const route = Object.freeze({
+    messageId, conversationId, actorId,
+    ...(identifier(message.thread_id) ? { threadId: message.thread_id } : {}),
+    ...(identifier(message.root_id) ? { rootId: message.root_id } : {}),
+    ...(identifier(message.parent_id) ? { parentId: message.parent_id } : {}),
+  });
+  return Object.freeze({
+    version: 1, channel: 'feishu', botId, fingerprint, eventId, messageId,
+    actor: Object.freeze({ kind: 'user', id: actorId,
+      ...(identifier(event.sender.sender_name) ? { name: event.sender.sender_name } : {}) }),
+    conversation: Object.freeze({ kind: message.chat_type === 'group' ? 'group' : 'dm', id: conversationId }),
+    mentions, mentionedAccount: mentions.some(mention => mention.id === botOpenId),
+    at: timestamp.toISOString(), text, reply: route,
+    replay: Object.freeze({ kind: 'provider-redelivery', resumeCursor: false, gapPossible: true }),
+  });
+}
+
+export class ExclusiveInboundConsumers {
+  #entries = new Map();
+
+  register(botId, { fingerprint, onEvent, signal }) {
+    if (this.#entries.has(botId)) throw refusal('consumer-conflict');
+    if (!/^[a-f0-9]{64}$/.test(fingerprint ?? '') || typeof onEvent !== 'function')
+      throw refusal('bad-request');
+    signal?.throwIfAborted();
+    const controller = new AbortController();
+    const entry = { fingerprint, onEvent, controller, dispose: undefined };
+    const dispose = () => {
+      if (this.#entries.get(botId) === entry) this.#entries.delete(botId);
+      controller.abort(refusal('consumer-unavailable'));
+      signal?.removeEventListener('abort', dispose);
+    };
+    entry.dispose = dispose;
+    this.#entries.set(botId, entry);
+    signal?.addEventListener('abort', dispose, { once: true });
+    return dispose;
+  }
+
+  async accept(botId, evidence, signal) {
+    const entry = this.#entries.get(botId);
+    if (!entry) throw refusal('consumer-unavailable');
+    if (entry.fingerprint !== evidence.fingerprint) throw refusal('account-changed');
+    const deliverySignal = signal
+      ? AbortSignal.any([signal, entry.controller.signal]) : entry.controller.signal;
+    deliverySignal.throwIfAborted();
+    let abort;
+    const interrupted = new Promise((_, reject) => {
+      abort = () => reject(deliverySignal.reason);
+      deliverySignal.addEventListener('abort', abort, { once: true });
+      if (deliverySignal.aborted) abort();
+    });
+    let result;
+    try {
+      result = await Promise.race([entry.onEvent(evidence, { signal: deliverySignal }), interrupted]);
+    } finally {
+      deliverySignal.removeEventListener('abort', abort);
+    }
+    deliverySignal.throwIfAborted();
+    if (this.#entries.get(botId) !== entry) throw refusal('consumer-unavailable');
+    if (result?.accepted !== true) throw refusal('ingress-not-accepted');
+    return { accepted: true };
+  }
+
+  signalFor(botId, fingerprint) {
+    const entry = this.#entries.get(botId);
+    if (!entry) throw refusal('consumer-unavailable');
+    if (entry.fingerprint !== fingerprint) throw refusal('account-changed');
+    return entry.controller.signal;
+  }
+
+  remove(botId) {
+    const entry = this.#entries.get(botId);
+    entry?.dispose();
+  }
+
+  close() {
+    for (const botId of this.#entries.keys()) this.remove(botId);
+  }
+}

package/src/channels/feishu/feishu-runtime.mjs

@@ -1,4 +1,5 @@
 import { createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
+import { readExternalHistory } from './history-reader.mjs';
 import { randomUUID } from 'node:crypto';
 import { FeishuHarnessBridge } from './bridge.mjs';
 import { cardActionProbeCard } from './feishu-cards.mjs';
@@ -134,6 +135,8 @@ export class FeishuRuntime {
   #repair;
   #client = null;
   #bridge = null;
+  #consumerMode;
+  #acceptExternal;
   #wsClient = null;
   #starting = null;
   #stopping = null;
@@ -157,6 +160,8 @@ export class FeishuRuntime {
 
   constructor({
     lark,
+    consumerMode = 'standalone',
+    acceptExternal,
     botId,
     appId,
     appSecret,
@@ -197,6 +202,8 @@ export class FeishuRuntime {
       throw new TypeError('FeishuRuntime requestTimeoutMs must be a positive number');
     }
 
+    this.#consumerMode = consumerMode;
+    this.#acceptExternal = acceptExternal;
     this.#lark = lark;
     this.#botId = nonEmptyString(botId);
     this.#appId = appId;
@@ -224,7 +231,7 @@ export class FeishuRuntime {
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#connectTimeoutMs = connectTimeoutMs;
     this.#requestTimeoutMs = requestTimeoutMs;
-    this.#slashCommands = Boolean(slashCommands);
+    this.#slashCommands = consumerMode !== 'external-consumer' && Boolean(slashCommands);
     this.#slashPanel = normalizeSlashPanelConfig(slashPanel);
     this.#wsAgent = wsAgent;
     this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'feishu', logger });
@@ -348,7 +355,7 @@ export class FeishuRuntime {
         client,
         initialText: t('已连接 DeepSeek Harness，正在思考…'),
       });
-      const bridge = new FeishuHarnessBridge({
+      const bridge = this.#consumerMode === 'external-consumer' ? null : new FeishuHarnessBridge({
         client,
         channel,
         harness: this.#harness,
@@ -381,6 +388,12 @@ export class FeishuRuntime {
 
       const dispatcher = new this.#lark.EventDispatcher({}).register({
         'im.message.receive_v1': (event) => {
+          if (this.#consumerMode === 'external-consumer') {
+            assertCurrentStart();
+            if (typeof this.#acceptExternal !== 'function')
+              throw Object.assign(new Error('consumer-unavailable'), { code: 'consumer-unavailable' });
+            return this.#acceptExternal(event, { signal });
+          }
           if (isCurrentStart()) void bridge.accept(event);
         },
         'im.message.reaction.created_v1': () => undefined,
@@ -389,7 +402,7 @@ export class FeishuRuntime {
         // subscribes card.action.trigger; the number-reply fallback covers
         // apps that do not).
         'card.action.trigger': (event) => {
-          if (!isCurrentStart()) return;
+          if (!isCurrentStart() || this.#consumerMode === 'external-consumer') return;
           this.#status.cardActionsReceived += 1;
           this.#status.lastCardActionAt = new Date().toISOString();
           if (!this.#consumeCardActionProbe(event)) void bridge.onCardAction(event);
@@ -675,6 +688,17 @@ export class FeishuRuntime {
     });
   }
 
+  async presentSessionSyncApproval(target, interaction, options = {}) {
+    if (!this.#status.ready || !this.#bridge) return false;
+    const actor = typeof target?.route?.openId === 'string' ? target.route.openId.trim() : '';
+    if (!actor) return false;
+    return this.#bridge.presentSessionSyncApproval(interaction, {
+      key: options.key, actor, validate: options.validate,
+      chatId: actor, receiveIdType: 'open_id',
+      send: (text) => this.sendProactiveText(target, text),
+    }, options);
+  }
+
   async sendProactiveText(target, text, { signal, format = 'plain', receipt = false } = {}) {
     if (!this.#status.ready || !this.#client) {
       const error = new Error('飞书机器人尚未连接');
@@ -734,6 +758,51 @@ export class FeishuRuntime {
     return { sent: true, receipt: { version: 1, messageId, conversationId } };
   }
 
+  async historyChecked(identity, route, query, { signal } = {}) {
+    const client = this.#client;
+    if (!client || this.#consumerMode !== 'external-consumer')
+      throw Object.assign(new Error('bot-not-connected'), { code: 'bot-not-connected' });
+    const result = await readExternalHistory(client, identity, route, query, signal);
+    signal?.throwIfAborted();
+    if (this.#client !== client)
+      throw Object.assign(new Error('bot-not-connected'), { code: 'bot-not-connected' });
+    return result;
+  }
+
+  async replyChecked(route, text, { signal } = {}) {
+    if (!route || typeof route.messageId !== 'string' || typeof route.conversationId !== 'string'
+      || typeof route.actorId !== 'string' || typeof text !== 'string' || !text.trim() || text.length > 4000)
+      throw Object.assign(new Error('bad-request'), { code: 'bad-request' });
+    const client = this.#client;
+    if (!client || this.#consumerMode !== 'external-consumer')
+      throw Object.assign(new Error('bot-not-connected'), { code: 'bot-not-connected' });
+    signal?.throwIfAborted();
+    const current = await client.im.v1.message.get({ path: { message_id: route.messageId } });
+    const source = current?.data?.items?.find(item => item.message_id === route.messageId);
+    if (current?.code || !source || source.deleted === true || source.chat_id !== route.conversationId
+      || source.sender?.sender_type !== 'user' || source.sender?.id_type !== 'open_id'
+      || source.sender?.id !== route.actorId || (source.thread_id || undefined) !== route.threadId
+      || (source.root_id || undefined) !== route.rootId || (source.parent_id || undefined) !== route.parentId)
+      throw Object.assign(new Error('stale-route'), { code: 'stale-route' });
+    signal?.throwIfAborted();
+    if (this.#client !== client) throw Object.assign(new Error('bot-not-connected'), { code: 'bot-not-connected' });
+    let response;
+    try {
+      response = await client.im.v1.message.reply({
+        path: { message_id: route.messageId },
+        data: { msg_type: 'text', content: JSON.stringify({ text }), reply_in_thread: Boolean(route.threadId) },
+      });
+    } catch (cause) {
+      // The request may have reached Lark. Do not turn an ambiguous result into
+      // a retryable pre-send failure or send again on the group mainline.
+      throw Object.assign(new Error('reply-result-unknown', { cause }), { code: 'reply-result-unknown' });
+    }
+    const messageId = response?.data?.message_id;
+    if (response?.code || typeof messageId !== 'string' || !messageId)
+      throw Object.assign(new Error('reply-result-unknown'), { code: 'reply-result-unknown' });
+    return { sent: true, messageId };
+  }
+
   /**
    * Queue one panel sync for the current config.
    *