@xmanrui/dsh-im 4.14.0 → 4.16.0

package/src/channels/wecom-app/wecom-app-controller.mjs

@@ -0,0 +1,440 @@
+import {
+  deriveWecomAppIdentity,
+  generateCallbackSecret,
+  maskCorpId,
+  validAgentId,
+  validApiBaseUrl,
+  validCorpId,
+} from './config-store.mjs';
+import {
+  connectionTestMessage,
+  connectionTestTargetUnavailable,
+} from '../shared/connection-test.mjs';
+import { t } from '../shared/i18n.mjs';
+import { publicMessageFailure } from '../shared/message-failure.mjs';
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function safeError(code, message) {
+  return Object.freeze({ code, message });
+}
+
+function validSecret(value) {
+  const secret = cleanString(value);
+  return Boolean(secret && /^[A-Za-z0-9_-]{16,128}$/.test(secret));
+}
+
+function validCallbackToken(value) {
+  const token = cleanString(value);
+  return Boolean(token && /^[A-Za-z0-9_-]{3,64}$/.test(token));
+}
+
+function validEncodingAesKey(value) {
+  const key = cleanString(value);
+  return Boolean(key && /^[A-Za-z0-9]{43}$/.test(key));
+}
+
+export class WecomAppController {
+  #credentials;
+  #configStore;
+  #createRuntime;
+  #deleteState;
+  #logger;
+  #buildCallbackUrl;
+  #runtimes = new Map();
+  #errors = new Map();
+  #revision = 0;
+  #closed = false;
+  #transitions = new Map();
+
+  constructor({
+    credentials,
+    configStore,
+    createRuntime,
+    deleteState = async () => {},
+    logger = console,
+    buildCallbackUrl = null,
+  }) {
+    if (!credentials || typeof credentials.resolve !== 'function'
+      || typeof credentials.set !== 'function' || typeof credentials.unset !== 'function') {
+      throw new TypeError('WecomAppController requires the DSH credential provider');
+    }
+    if (!configStore || typeof configStore.list !== 'function'
+      || typeof configStore.save !== 'function' || typeof configStore.remove !== 'function') {
+      throw new TypeError('WecomAppController requires a config store');
+    }
+    if (typeof createRuntime !== 'function') throw new TypeError('createRuntime is required');
+    this.#credentials = credentials;
+    this.#configStore = configStore;
+    this.#createRuntime = createRuntime;
+    this.#deleteState = deleteState;
+    this.#logger = logger;
+    this.#buildCallbackUrl = typeof buildCallbackUrl === 'function' ? buildCallbackUrl : null;
+  }
+
+  async initialize() {
+    if (this.#closed) return this.status();
+    for (const config of this.#configStore.list()) {
+      await this.#withBotTransition(config.botId, async () => {
+        if (this.#runtimes.has(config.botId)) return;
+        const secrets = await this.#resolveSecrets(config);
+        if (!secrets) {
+          this.#errors.set(config.botId, safeError('missing-credentials', t('企业微信应用凭据缺失，请重新绑定。')));
+          return;
+        }
+        try {
+          await this.#startRuntime(config, secrets);
+          this.#errors.delete(config.botId);
+        } catch (error) {
+          this.#errors.set(config.botId, safeError('connection-failed', t('企业微信应用连接未就绪，插件会自动重试。')));
+          this.#logger.warn?.(`[dsh-im:wecom-app] bot ${config.botId} failed to initialize`, error);
+        } finally {
+          this.#touch();
+        }
+      });
+    }
+    return this.status();
+  }
+
+  async bindApp({
+    corpId,
+    agentId,
+    secret,
+    token,
+    encodingAESKey,
+    apiBaseUrl,
+    callbackBaseUrl,
+    streamEnabled,
+  } = {}) {
+    if (this.#closed) throw new Error('Enterprise WeChat app controller is closed');
+    const normalizedCorpId = cleanString(corpId);
+    const normalizedAgentId = cleanString(agentId);
+    const normalizedSecret = cleanString(secret);
+    const normalizedToken = cleanString(token);
+    const normalizedAesKey = cleanString(encodingAESKey);
+    if (!validCorpId(normalizedCorpId)) throw new TypeError(t('请输入正确的企业 ID（例如 ww1234567890abcdef）。'));
+    if (!validAgentId(normalizedAgentId)) throw new TypeError(t('请输入正确的应用 AgentId（纯数字）。'));
+    if (!validSecret(normalizedSecret)) throw new TypeError(t('应用 Secret 格式不正确。'));
+    if (!validCallbackToken(normalizedToken)) throw new TypeError(t('回调 Token 格式不正确。'));
+    if (!validEncodingAesKey(normalizedAesKey)) throw new TypeError(t('EncodingAESKey 必须是 43 位字母或数字。'));
+    if (!validApiBaseUrl(apiBaseUrl ?? undefined)) throw new TypeError(t('代理地址必须是 http(s) 地址。'));
+    if (!validApiBaseUrl(callbackBaseUrl ?? undefined)) throw new TypeError(t('回调基址必须是 http(s) 地址。'));
+    const identity = deriveWecomAppIdentity({ corpId: normalizedCorpId, agentId: normalizedAgentId });
+    await this.#withBotTransition(identity.botId, async () => {
+      if (this.#closed) throw new Error('Enterprise WeChat app controller is closed');
+      const previousConfig = this.#configStore.getByCorpAgent(normalizedCorpId, normalizedAgentId);
+      const botId = identity.botId;
+      const config = {
+        botId,
+        corpId: normalizedCorpId,
+        agentId: normalizedAgentId,
+        secretRef: identity.secretRef,
+        callbackTokenRef: identity.callbackTokenRef,
+        callbackKeyRef: identity.callbackKeyRef,
+        callbackSecret: previousConfig?.callbackSecret ?? generateCallbackSecret(),
+        apiBaseUrl: cleanString(apiBaseUrl) ?? undefined,
+        callbackBaseUrl: cleanString(callbackBaseUrl) ?? undefined,
+        streamEnabled: streamEnabled !== false,
+        createdAt: previousConfig?.createdAt ?? new Date().toISOString(),
+        connectedAt: new Date().toISOString(),
+      };
+      const previous = await this.#resolveSecrets(config);
+      await this.#setSecrets(identity, {
+        corpSecret: normalizedSecret,
+        token: normalizedToken,
+        encodingAESKey: normalizedAesKey,
+      });
+      try {
+        await this.#configStore.save(config);
+      } catch (error) {
+        await this.#restoreSecrets(identity, previous);
+        throw error;
+      }
+      try {
+        await this.#startRuntime(config, {
+          corpSecret: normalizedSecret,
+          token: normalizedToken,
+          encodingAESKey: normalizedAesKey,
+        });
+        this.#errors.delete(botId);
+      } catch (error) {
+        this.#errors.set(botId, safeError('connection-failed', t('企业微信应用已绑定，但尚未就绪。')));
+        this.#logger.warn?.(`[dsh-im:wecom-app] bot ${botId} credential connection failed`, error);
+      }
+      this.#touch();
+    });
+    return this.status();
+  }
+
+  async updateAppSettings(botId, { apiBaseUrl, callbackBaseUrl, streamEnabled } = {}) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    await this.#withBotTransition(botId, async () => {
+      const previous = await this.#resolveSecrets(config);
+      const patch = {};
+      if (apiBaseUrl !== undefined) {
+        if (!validApiBaseUrl(apiBaseUrl)) throw new TypeError(t('代理地址必须是 http(s) 地址。'));
+        patch.apiBaseUrl = cleanString(apiBaseUrl) ?? null;
+      }
+      if (callbackBaseUrl !== undefined) {
+        if (!validApiBaseUrl(callbackBaseUrl)) throw new TypeError(t('回调基址必须是 http(s) 地址。'));
+        patch.callbackBaseUrl = cleanString(callbackBaseUrl) ?? null;
+      }
+      if (streamEnabled !== undefined) patch.streamEnabled = streamEnabled === true;
+      if (Object.keys(patch).length === 0) return;
+      try {
+        await this.#configStore.update(botId, patch);
+      } catch (error) {
+        await this.#restoreSecrets(config, previous);
+        throw error;
+      }
+      const updated = this.#configStore.get(botId);
+      const runtime = this.#runtimes.get(botId);
+      if (streamEnabled !== undefined && runtime && typeof runtime.setStreamEnabled === 'function') {
+        runtime.setStreamEnabled(patch.streamEnabled);
+      }
+      if (apiBaseUrl !== undefined) {
+        // The API client bakes in the base URL; restart to pick up the change.
+        const secrets = await this.#resolveSecrets(updated);
+        if (secrets) {
+          try {
+            await this.#startRuntime(updated, secrets);
+          } catch (error) {
+            this.#errors.set(botId, safeError('connection-failed', t('企业微信应用已更新，但尚未就绪。')));
+            this.#logger.warn?.(`[dsh-im:wecom-app] bot ${botId} restart after settings update failed`, error);
+          }
+        }
+      }
+      this.#errors.delete(botId);
+      this.#touch();
+    });
+    return this.status();
+  }
+
+  async resetCallbackSecret(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    await this.#withBotTransition(botId, async () => {
+      await this.#configStore.update(botId, { callbackSecret: generateCallbackSecret() });
+      const updated = this.#configStore.get(botId);
+      const secrets = await this.#resolveSecrets(updated);
+      if (secrets && this.#runtimes.has(botId)) {
+        try {
+          await this.#startRuntime(updated, secrets);
+        } catch (error) {
+          this.#errors.set(botId, safeError('connection-failed', t('回调密钥已重置，但机器人重启失败，请手动重连。')));
+          this.#logger.warn?.(`[dsh-im:wecom-app] bot ${botId} restart after secret reset failed`, error);
+        }
+      }
+      this.#touch();
+    });
+    return this.status();
+  }
+
+  async reconnectBot(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    await this.#withBotTransition(botId, async () => {
+      const secrets = await this.#resolveSecrets(config);
+      if (!secrets) throw new Error('Enterprise WeChat app bot credentials are missing');
+      try {
+        await this.#startRuntime(config, secrets);
+        this.#errors.delete(botId);
+      } catch (error) {
+        this.#errors.set(botId, safeError('connection-failed', t('企业微信应用仍未就绪，请稍后重试。')));
+        throw error;
+      } finally {
+        this.#touch();
+      }
+    });
+    return this.status();
+  }
+
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        throw connectionTestTargetUnavailable(t('企业微信应用'));
+      }
+      return runtime.sendConnectionTest(connectionTestMessage(
+        t('企业微信应用（{corpId}）', { corpId: maskCorpId(config.corpId) }),
+        t('企业微信应用'),
+      ));
+    });
+  }
+
+  async sendProactiveText(botId, target, text, options = {}) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendProactiveText !== 'function') {
+        const error = new Error(t('企业微信应用当前离线'));
+        error.code = 'bot-not-connected';
+        throw error;
+      }
+      return runtime.sendProactiveText(target, text, options);
+    });
+  }
+
+  async deleteBot(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Enterprise WeChat app bot');
+    await this.#withBotTransition(botId, async () => {
+      const previous = await this.#resolveSecrets(config);
+      await this.#stopRuntime(botId);
+      try {
+        await this.#credentials.unset(config.secretRef);
+        await this.#credentials.unset(config.callbackTokenRef);
+        await this.#credentials.unset(config.callbackKeyRef);
+        await this.#configStore.remove(botId);
+      } catch (error) {
+        if (previous) {
+          await this.#setSecrets(config, previous).catch(() => undefined);
+          await this.#startRuntime(config, previous).catch(() => undefined);
+        }
+        throw new Error('Unable to remove the Enterprise WeChat app bot safely.', { cause: error });
+      }
+      await this.#deleteState({ botId, config }).catch((error) => {
+        this.#logger.warn?.(`[dsh-im:wecom-app] bot ${botId} state cleanup failed:`, error);
+      });
+      this.#errors.delete(botId);
+      this.#touch();
+    });
+    return this.status();
+  }
+
+  status() {
+    const bots = this.#configStore.list().map((config) => {
+      const runtimeStatus = this.#runtimes.get(config.botId)?.status ?? null;
+      const connected = runtimeStatus?.ready === true
+        && runtimeStatus.wecomAppConnectionState === 'connected'
+        && runtimeStatus.harnessReachable === true;
+      const state = connected ? 'connected'
+        : runtimeStatus?.wecomAppConnectionState === 'connecting' ? 'connecting'
+          : this.#errors.has(config.botId) || runtimeStatus?.wecomAppConnectionState === 'failed'
+            ? 'error' : 'offline';
+      const callbackUrl = typeof this.#buildCallbackUrl === 'function'
+        ? this.#buildCallbackUrl(config) ?? null
+        : null;
+      return {
+        botId: config.botId,
+        state,
+        connected,
+        configured: true,
+        bot: {
+          name: t('企业微信应用'),
+          corpIdMasked: maskCorpId(config.corpId),
+          agentId: config.agentId,
+          apiBaseUrl: config.apiBaseUrl ?? null,
+          callbackBaseUrl: config.callbackBaseUrl ?? null,
+          streamEnabled: config.streamEnabled !== false,
+          callbackUrl,
+        },
+        health: {
+          status: connected ? 'healthy' : state === 'error' ? 'error' : 'offline',
+          summary: connected ? t('企业微信应用回调通道就绪')
+            : state === 'error' ? t('企业微信应用连接未就绪，插件会自动重试') : t('企业微信应用当前离线'),
+          lastCheckedAt: runtimeStatus?.lastCheckedAt ?? null,
+          lastConnectedAt: runtimeStatus?.lastConnectedAt ?? null,
+        },
+        stats: {
+          messagesReceived: runtimeStatus?.messagesReceived ?? 0,
+          messagesReplied: runtimeStatus?.messagesReplied ?? 0,
+        },
+        lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
+        error: structuredClone(this.#errors.get(config.botId) ?? null),
+      };
+    });
+    const connectedCount = bots.filter((bot) => bot.connected).length;
+    return {
+      schemaVersion: 1,
+      revision: this.#revision,
+      state: bots.length === 0 ? 'disconnected'
+        : connectedCount === bots.length ? 'connected'
+          : connectedCount > 0 ? 'degraded' : 'offline',
+      bots,
+      totals: { configured: bots.length, connected: connectedCount },
+    };
+  }
+
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    await Promise.allSettled([...this.#transitions.values()]);
+    await Promise.allSettled([...this.#runtimes.keys()].map((botId) => this.#stopRuntime(botId)));
+  }
+
+  async #startRuntime(config, secrets) {
+    if (this.#closed) throw new Error('Enterprise WeChat app controller is closed');
+    await this.#stopRuntime(config.botId);
+    if (this.#closed) throw new Error('Enterprise WeChat app controller is closed');
+    const runtime = await this.#createRuntime({ botId: config.botId, config, secrets });
+    if (!runtime || typeof runtime.start !== 'function' || typeof runtime.stop !== 'function') {
+      throw new TypeError('createRuntime returned an invalid Enterprise WeChat app runtime');
+    }
+    this.#runtimes.set(config.botId, runtime);
+    try {
+      await runtime.start();
+    } catch (error) {
+      await runtime.stop().catch(() => undefined);
+      this.#runtimes.delete(config.botId);
+      throw error;
+    }
+  }
+
+  async #stopRuntime(botId) {
+    const runtime = this.#runtimes.get(botId);
+    this.#runtimes.delete(botId);
+    await runtime?.stop().catch((error) => {
+      this.#logger.warn?.(`[dsh-im:wecom-app] bot ${botId} failed to stop cleanly:`, error);
+    });
+  }
+
+  async #resolveSecrets(config) {
+    const corpSecret = await this.#resolveSecret(config.secretRef);
+    const token = await this.#resolveSecret(config.callbackTokenRef);
+    const encodingAESKey = await this.#resolveSecret(config.callbackKeyRef);
+    if (!corpSecret || !token || !encodingAESKey) return null;
+    return { corpSecret, token, encodingAESKey };
+  }
+
+  async #setSecrets(identity, { corpSecret, token, encodingAESKey }) {
+    await this.#credentials.set(identity.secretRef, corpSecret);
+    await this.#credentials.set(identity.callbackTokenRef, token);
+    await this.#credentials.set(identity.callbackKeyRef, encodingAESKey);
+  }
+
+  async #resolveSecret(ref) {
+    const result = await this.#credentials.resolve(ref).catch(() => undefined);
+    return cleanString(result?.value);
+  }
+
+  async #restoreSecrets(identity, previous) {
+    if (previous) {
+      await this.#setSecrets(identity, previous).catch(() => undefined);
+      return;
+    }
+    await this.#credentials.unset(identity.secretRef).catch(() => undefined);
+    await this.#credentials.unset(identity.callbackTokenRef).catch(() => undefined);
+    await this.#credentials.unset(identity.callbackKeyRef).catch(() => undefined);
+  }
+
+  #withBotTransition(botId, operation) {
+    const previous = this.#transitions.get(botId) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    const settled = current.finally(() => {
+      if (this.#transitions.get(botId) === settled) this.#transitions.delete(botId);
+    });
+    this.#transitions.set(botId, settled);
+    return settled;
+  }
+
+  #touch() {
+    this.#revision += 1;
+  }
+}

package/src/channels/wecom-app/wecom-app-runtime.mjs

@@ -0,0 +1,221 @@
+import {
+  WecomAppApi,
+  WecomAppError,
+  createUserCrypto,
+  splitUtf8ByBytes,
+} from './wecom-app-api.mjs';
+import { WecomAppBridge } from './wecom-app-bridge.mjs';
+import { sendRememberedConnectionTest } from '../shared/connection-test.mjs';
+import { t } from '../shared/i18n.mjs';
+
+function timeoutError(message) {
+  const error = new Error(message);
+  error.code = 'connect-timeout';
+  return error;
+}
+
+export function createWecomAppRuntimeStatus() {
+  return {
+    startedAt: null,
+    ready: false,
+    wecomAppConnectionState: 'idle',
+    harnessReachable: false,
+    lastCheckedAt: null,
+    lastConnectedAt: null,
+    lastError: null,
+    messagesReceived: 0,
+    messagesReplied: 0,
+    lastMessageAt: null,
+    lastReplyAt: null,
+  };
+}
+
+// One runtime per bound self-built application. Unlike the WeCom smart-robot
+// channel there is no outbound WebSocket: the runtime registers a callback
+// route on the shared WecomAppCallbackServer and replies either passively
+// (stream) or through the cgi-bin message/send API.
+export class WecomAppRuntime {
+  #config;
+  #secrets;
+  #harness;
+  #state;
+  #contextEnhancement;
+  #accessPolicy;
+  #logger;
+  #callbackServer;
+  #replyTimeoutMs;
+  #streamEnabled;
+  #status = createWecomAppRuntimeStatus();
+  #api = null;
+  #bridge = null;
+  #started = false;
+  #controller = new AbortController();
+
+  constructor({
+    config,
+    secrets,
+    harness,
+    state,
+    contextEnhancement,
+    accessPolicy,
+    logger = console,
+    callbackServer,
+    replyTimeoutMs = 600_000,
+  }) {
+    if (!config || !secrets || !harness || !state) {
+      throw new TypeError('WecomAppRuntime requires config, secrets, Harness, and state');
+    }
+    if (!callbackServer || typeof callbackServer.registerRoute !== 'function') {
+      throw new TypeError('WecomAppRuntime requires the shared WecomAppCallbackServer');
+    }
+    this.#config = config;
+    this.#secrets = secrets;
+    this.#harness = harness;
+    this.#state = state;
+    this.#contextEnhancement = contextEnhancement;
+    this.#accessPolicy = accessPolicy;
+    this.#logger = logger;
+    this.#callbackServer = callbackServer;
+    this.#replyTimeoutMs = replyTimeoutMs;
+    this.#streamEnabled = config.streamEnabled !== false;
+  }
+
+  get status() {
+    return structuredClone(this.#status);
+  }
+
+  get streamEnabled() {
+    return this.#streamEnabled;
+  }
+
+  setStreamEnabled(enabled) {
+    this.#streamEnabled = enabled === true;
+  }
+
+  async start() {
+    if (this.#started) return this.status;
+    const corpSecret = this.#secrets.corpSecret;
+    const token = this.#secrets.token;
+    const encodingAESKey = this.#secrets.encodingAESKey;
+    if (!corpSecret || !token || !encodingAESKey) {
+      this.#status.lastError = 'missing-credentials';
+      throw new WecomAppError('missing-credentials', t('企业微信应用凭据不完整，请重新绑定。'));
+    }
+    this.#status.startedAt = new Date().toISOString();
+    this.#status.lastError = null;
+    this.#status.wecomAppConnectionState = 'connecting';
+    await this.#harness.ensureRunning({ signal: this.#signal() });
+    this.#status.harnessReachable = true;
+
+    this.#api = new WecomAppApi({
+      corpId: this.#config.corpId,
+      corpSecret,
+      agentId: this.#config.agentId,
+      apiBaseUrl: this.#config.apiBaseUrl,
+      logger: this.#logger,
+      signal: undefined,
+    });
+    this.#bridge = new WecomAppBridge({
+      api: this.#api,
+      harness: this.#harness,
+      state: this.#state,
+      status: this.#status,
+      contextEnhancement: this.#contextEnhancement,
+      accessPolicy: this.#accessPolicy,
+      logger: this.#logger,
+      replyTimeoutMs: this.#replyTimeoutMs,
+      signal: this.#signal(),
+      streamRegistry: this.#callbackServer,
+    });
+    await this.#callbackServer.registerRoute({
+      botId: this.#config.botId,
+      callbackSecret: this.#config.callbackSecret,
+      cryptoFor: () => createUserCrypto({
+        token,
+        encodingAESKey,
+        corpId: this.#config.corpId,
+      }),
+      streamEnabled: () => this.#streamEnabled,
+      onInbound: async ({ kind, message, stream }) => {
+        if (kind === 'event') {
+          await this.#bridge.acceptEvent(message);
+          return;
+        }
+        const sink = stream
+          ? {
+              streamId: stream.streamId,
+              append: (chunk, options) => this.#callbackServer.appendStream(stream.streamId, chunk, options),
+              finish: (error) => this.#callbackServer.finishStream(stream.streamId, { error }),
+              refreshes: () => this.#callbackServer.getStream(stream.streamId)?.refreshes ?? 0,
+              finished: () => this.#callbackServer.getStream(stream.streamId)?.finished === true,
+            }
+          : null;
+        await this.#bridge.accept(message, { sink });
+      },
+    });
+    this.#started = true;
+    const now = Date.now();
+    this.#status.ready = true;
+    this.#status.wecomAppConnectionState = 'connected';
+    this.#status.lastCheckedAt = now;
+    this.#status.lastConnectedAt = now;
+    return this.status;
+  }
+
+  async stop() {
+    this.#controller.abort(new DOMException('WecomAppRuntime stopped', 'AbortError'));
+    if (this.#bridge) {
+      await this.#bridge.close().catch((error) => {
+        this.#logger.warn?.('[dsh-im:wecom-app] bridge stop failed:', error);
+      });
+    }
+    this.#bridge = null;
+    this.#api = null;
+    this.#callbackServer.unregisterRoute(this.#config.botId);
+    this.#started = false;
+    this.#status.ready = false;
+    this.#status.wecomAppConnectionState = 'idle';
+    return this.status;
+  }
+
+  async sendConnectionTest(text) {
+    return sendRememberedConnectionTest({
+      state: this.#state,
+      text,
+      channelLabel: t('企业微信应用'),
+      send: async ({ toUserId }, content) => {
+        if (!this.#started || !this.#api) {
+          throw new WecomAppError('not-connected', 'Enterprise WeChat app runtime is not connected');
+        }
+        await this.#api.sendText({ userId: toUserId, content });
+      },
+    });
+  }
+
+  async sendProactiveText(target, text, { signal } = {}) {
+    const chatId = typeof target?.route?.chatId === 'string' ? target.route.chatId.trim() : '';
+    if ((target?.kind !== 'user') || !chatId) {
+      const error = new TypeError('Invalid Enterprise WeChat app proactive delivery target');
+      error.code = 'invalid-target';
+      throw error;
+    }
+    if (!this.#started || !this.#api) {
+      const error = new WecomAppError('bot-not-connected', 'Enterprise WeChat app runtime is not connected');
+      error.code = 'bot-not-connected';
+      throw error;
+    }
+    signal?.throwIfAborted();
+    const chunks = splitUtf8ByBytes(text);
+    for (const chunk of chunks) {
+      if (!chunk) continue;
+      await this.#api.sendText({ userId: chatId, content: chunk, signal });
+    }
+    return { sent: true };
+  }
+
+  #signal() {
+    // Each start() gets a fresh controller; stop() aborts the latest one.
+    if (this.#controller.signal.aborted) this.#controller = new AbortController();
+    return this.#controller.signal;
+  }
+}