@xmanrui/dsh-im 0.10.0 → 0.12.0

package/src/channels/shared/model-command.mjs

@@ -0,0 +1,314 @@
+import { splitWorkspaceCommandMessage } from './workspace-command.mjs';
+import { WORKSPACE_SESSION_STALE } from './workspace-session.mjs';
+import { withSessionBindingLock } from './session-binding-lock.mjs';
+
+const MODEL_COMMAND = /^\/model(?=$|\s)/i;
+const MODELS_COMMAND = /^\/models(?=$|\s)/i;
+const MODEL_USAGE = '用法：/model <provider>/<model>';
+const MODELS_USAGE = '用法：/models（不带参数）';
+const SESSION_BINDING_CHANGED = 'session-binding-changed';
+const UNSAFE_DISPLAY_TEXT_GLOBAL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu;
+
+function commandResult(message) {
+  return {
+    handled: true,
+    message,
+    messages: splitWorkspaceCommandMessage(message),
+  };
+}
+
+function safeDisplayText(value) {
+  if (typeof value !== 'string') return '';
+  return value.replace(UNSAFE_DISPLAY_TEXT_GLOBAL, ' ').replace(/\s+/gu, ' ').trim();
+}
+
+function rpcOptions(signal) {
+  return signal ? { signal } : {};
+}
+
+function normalizeCatalog(value, { requireCurrent = false } = {}) {
+  if (!value || typeof value !== 'object'
+    || !Array.isArray(value.groups) || !Array.isArray(value.failures)) {
+    throw new TypeError('Harness returned an invalid model catalog');
+  }
+  const groups = value.groups.map((group) => {
+    if (!group || typeof group !== 'object'
+      || typeof group.id !== 'string' || !group.id
+      || typeof group.name !== 'string' || !group.name
+      || !Array.isArray(group.models)) {
+      throw new TypeError('Harness returned an invalid model provider group');
+    }
+    return {
+      id: group.id,
+      name: group.name,
+      models: group.models.map((model) => {
+        if (!model || typeof model !== 'object'
+          || typeof model.id !== 'string' || !model.id
+          || typeof model.name !== 'string' || !model.name) {
+          throw new TypeError('Harness returned an invalid model');
+        }
+        return { id: model.id, name: model.name };
+      }),
+    };
+  });
+  const failures = value.failures.map((failure) => {
+    if (!failure || typeof failure !== 'object'
+      || typeof failure.id !== 'string' || !failure.id
+      || typeof failure.name !== 'string' || !failure.name) {
+      throw new TypeError('Harness returned an invalid model provider failure');
+    }
+    return { id: failure.id, name: failure.name };
+  });
+  let current = null;
+  if (value.current !== undefined) {
+    if (!value.current || typeof value.current !== 'object'
+      || typeof value.current.provider !== 'string' || !value.current.provider
+      || typeof value.current.model !== 'string' || !value.current.model) {
+      throw new TypeError('Harness returned an invalid current model');
+    }
+    current = { provider: value.current.provider, model: value.current.model };
+  } else if (requireCurrent) {
+    throw new TypeError('Harness returned no current model');
+  }
+  return { groups, failures, current };
+}
+
+function modelId(provider, model) {
+  return `${provider}/${model}`;
+}
+
+function matchingModel(catalog, requested) {
+  for (const group of catalog.groups) {
+    for (const model of group.models) {
+      if (modelId(group.id, model.id) === requested) {
+        return { provider: group.id, model: model.id };
+      }
+    }
+  }
+  return null;
+}
+
+function formatCatalog(catalog) {
+  const currentId = catalog.current
+    ? modelId(catalog.current.provider, catalog.current.model)
+    : null;
+  const lines = ['可用模型：'];
+  if (catalog.groups.length === 0) lines.push('', '当前没有可用模型。');
+  for (const group of catalog.groups) {
+    lines.push('', safeDisplayText(group.name) || safeDisplayText(group.id));
+    for (const model of group.models) {
+      const id = modelId(group.id, model.id);
+      lines.push(`- ${safeDisplayText(id)}${id === currentId ? '（当前）' : ''}`);
+    }
+  }
+  if (catalog.failures.length > 0) {
+    lines.push('', '以下模型提供方暂时不可用：');
+    for (const failure of catalog.failures) {
+      lines.push(`- ${safeDisplayText(failure.name) || safeDisplayText(failure.id)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function currentModelMessage(current) {
+  return [
+    '当前模型：',
+    modelId(current.provider, current.model),
+    '',
+    '查看全部模型：/models',
+    '切换模型：/model <provider>/<model>',
+  ].join('\n');
+}
+
+function noSessionMessage() {
+  return [
+    '当前聊天还没有会话。',
+    '',
+    '查看模型：/models',
+    '选择模型：/model <provider>/<model>',
+  ].join('\n');
+}
+
+function errorCode(error) {
+  return error?.code ?? error?.failure?.code;
+}
+
+function modelErrorMessage(error, action) {
+  const code = errorCode(error);
+  if (code === 'agent-busy') {
+    return '当前任务正在运行，请等待完成或先发送 /stop。';
+  }
+  if (code === 'session-not-found') {
+    return '当前聊天绑定的会话已不存在，请重试。';
+  }
+  if (code === 'model-unavailable') {
+    return '无法切换到该模型。模型当前不可用，或不支持当前会话中的图片。';
+  }
+  if (code === WORKSPACE_SESSION_STALE || code === 'workspace-bot-not-found') {
+    return '工作区或机器人状态已发生变化，请重试。';
+  }
+  if (code === SESSION_BINDING_CHANGED) {
+    return '当前聊天绑定的会话已发生变化，请重试。';
+  }
+  if (code === 'cancelled' || error?.name === 'AbortError') {
+    return action === 'list' ? '获取模型列表已取消。' : '模型切换已取消。';
+  }
+  return action === 'list'
+    ? '暂时无法获取模型列表，请稍后重试。'
+    : '模型切换失败，请稍后重试。';
+}
+
+async function boundSession(harness, state, key, options) {
+  if (typeof state?.sessionFor !== 'function') return null;
+  const sessionId = state.sessionFor(key);
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  if (typeof harness?.workspaceSession !== 'function') {
+    throw new TypeError('Harness does not support workspace sessions');
+  }
+  const session = harness.workspaceSession(sessionId);
+  if (!session || typeof session.sessionExists !== 'function') {
+    throw new TypeError('Harness returned an invalid workspace session');
+  }
+  if (await session.sessionExists(options)) return { sessionId, session };
+  if (typeof state.clearSession === 'function' && state.sessionFor(key) === sessionId) {
+    await state.clearSession(key);
+  }
+  return null;
+}
+
+async function sessionIsBusy(session, control, options) {
+  if (typeof session?.isRunning !== 'function'
+    || typeof session?.hasActiveTurn !== 'function') {
+    throw new TypeError('Harness session does not expose run state');
+  }
+  if (await session.isRunning(options)) return true;
+  return Boolean(await session.hasActiveTurn(control, options));
+}
+
+async function listCatalog(harness, options) {
+  if (typeof harness?.listModels !== 'function') {
+    throw new TypeError('Harness does not support listing models');
+  }
+  return normalizeCatalog(await harness.listModels(options));
+}
+
+async function sessionCatalog(session, options) {
+  if (typeof session?.models !== 'function') {
+    throw new TypeError('Harness session does not support listing models');
+  }
+  return normalizeCatalog(await session.models(options), { requireCurrent: true });
+}
+
+function isModelsCommand(command) {
+  return MODELS_COMMAND.test(command);
+}
+
+export function isModelCommand(text) {
+  if (typeof text !== 'string') return false;
+  const command = text.trim();
+  return MODELS_COMMAND.test(command) || MODEL_COMMAND.test(command);
+}
+
+export async function runModelCommand(text, harness, state, key, options = {}) {
+  if (!isModelCommand(text)) return null;
+  const command = text.trim();
+  if (options.hasImages) {
+    return commandResult('模型命令仅支持纯文字，请移除图片后重试。');
+  }
+  const requestOptions = rpcOptions(options.signal);
+
+  if (isModelsCommand(command)) {
+    if (!/^\/models[ \t]*$/iu.test(command)) return commandResult(MODELS_USAGE);
+    try {
+      const bound = await boundSession(harness, state, key, requestOptions);
+      const catalog = bound
+        ? await sessionCatalog(bound.session, requestOptions)
+        : await listCatalog(harness, requestOptions);
+      return commandResult(formatCatalog(catalog));
+    } catch (error) {
+      return commandResult(modelErrorMessage(error, 'list'));
+    }
+  }
+
+  const match = /^\/model(?:[ \t]+([^\s]+))?[ \t]*$/iu.exec(command);
+  if (!match) return commandResult(MODEL_USAGE);
+  const requested = match[1];
+  if (!requested) {
+    try {
+      const bound = await boundSession(harness, state, key, requestOptions);
+      if (!bound) return commandResult(noSessionMessage());
+      const catalog = await sessionCatalog(bound.session, requestOptions);
+      return commandResult(currentModelMessage(catalog.current));
+    } catch (error) {
+      return commandResult(modelErrorMessage(error, 'select'));
+    }
+  }
+  if (!requested.includes('/') || requested.startsWith('/') || requested.endsWith('/')) {
+    return commandResult(MODEL_USAGE);
+  }
+  if (options.pendingInteraction) {
+    return commandResult([
+      '当前任务正在等待你的回答或审批。',
+      '',
+      '请先处理当前请求，或者发送 /stop 停止任务。',
+    ].join('\n'));
+  }
+
+  try {
+    return await withSessionBindingLock(state, key, async () => {
+      const bound = await boundSession(harness, state, key, requestOptions);
+      if (bound && await sessionIsBusy(bound.session, options.control, requestOptions)) {
+        return commandResult('当前任务正在运行，请等待完成或先发送 /stop。');
+      }
+
+      const catalog = bound
+        ? await sessionCatalog(bound.session, requestOptions)
+        : await listCatalog(harness, requestOptions);
+      const selection = matchingModel(catalog, requested);
+      if (!selection) {
+        return commandResult([
+          `没有找到模型：${safeDisplayText(requested)}`,
+          '',
+          '请发送 /models 查看可用模型。',
+        ].join('\n'));
+      }
+
+      if (bound) {
+        if (typeof bound.session.selectModel !== 'function') {
+          throw new TypeError('Harness session does not support model selection');
+        }
+        await bound.session.selectModel(selection, requestOptions);
+      } else {
+        if (typeof harness?.createSession !== 'function'
+          || typeof harness?.workspaceSession !== 'function'
+          || typeof state?.sessionFor !== 'function'
+          || typeof state?.setSession !== 'function') {
+          throw new TypeError('Harness cannot create a conversation session');
+        }
+        const sessionId = await harness.createSession(requestOptions);
+        if (typeof sessionId !== 'string' || !sessionId) {
+          throw new TypeError('Harness returned an invalid session id');
+        }
+        const session = harness.workspaceSession(sessionId);
+        if (!session || typeof session.selectModel !== 'function') {
+          throw new TypeError('Harness session does not support model selection');
+        }
+        await session.selectModel(selection, requestOptions);
+        const currentSessionId = state.sessionFor(key);
+        if (typeof currentSessionId === 'string' && currentSessionId) {
+          const changed = new Error('Conversation binding changed during model selection');
+          changed.code = SESSION_BINDING_CHANGED;
+          throw changed;
+        }
+        if (await state.setSession(key, sessionId) === false) {
+          const stale = new Error('Workspace changed while binding the new session');
+          stale.code = WORKSPACE_SESSION_STALE;
+          throw stale;
+        }
+      }
+      return commandResult(`模型已切换为：\n${modelId(selection.provider, selection.model)}\n\n后续消息将使用该模型。`);
+    });
+  } catch (error) {
+    return commandResult(modelErrorMessage(error, 'select'));
+  }
+}

package/src/channels/shared/session-binding-lock.mjs

@@ -0,0 +1,40 @@
+const bindingLocks = new WeakMap();
+
+function stateLocks(state) {
+  let locks = bindingLocks.get(state);
+  if (!locks) {
+    locks = new Map();
+    bindingLocks.set(state, locks);
+  }
+  return locks;
+}
+
+/**
+ * Serialize the short Session binding transaction for one conversation.
+ * The caller must keep long-running Session work, such as ask(), outside.
+ */
+export async function withSessionBindingLock(state, key, operation) {
+  const stateType = typeof state;
+  if ((stateType !== 'object' && stateType !== 'function') || state === null) {
+    throw new TypeError('state is required');
+  }
+  if (typeof key !== 'string' || !key) throw new TypeError('conversation key is required');
+  if (typeof operation !== 'function') throw new TypeError('operation is required');
+
+  const locks = stateLocks(state);
+  const previous = locks.get(key) ?? Promise.resolve();
+  let release;
+  const current = new Promise((resolve) => { release = resolve; });
+  locks.set(key, current);
+
+  await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (locks.get(key) === current) {
+      locks.delete(key);
+      if (locks.size === 0) bindingLocks.delete(state);
+    }
+  }
+}

package/src/channels/shared/text-harness-bridge.mjs

@@ -1,5 +1,17 @@
 import { runWorkspaceCommand } from './workspace-command.mjs';
 import { runCompactCommand } from './compact-command.mjs';
+import {
+  isControlCommand,
+  runControlCommand,
+} from './control-command.mjs';
+import {
+  rememberConnectionTestTarget,
+  sendRememberedConnectionTest,
+} from './connection-test.mjs';
+import {
+  isModelCommand,
+  runModelCommand,
+} from './model-command.mjs';
 import { askInWorkspaceSession } from './workspace-session.mjs';
 import { HarnessApprovalQueue } from './harness-approval.mjs';
 import {
@@ -52,6 +64,7 @@ export class TextHarnessBridge {
   #interactionKeys = new Map();
   #acceptedMessageIds = new Set();
   #approvalTasks = new Set();
+  #commandTasks = new Set();
   #approvals;
 
   constructor({
@@ -97,9 +110,33 @@ export class TextHarnessBridge {
       return Promise.resolve();
     }
     this.#acceptedMessageIds.add(messageId);
+    if (normalized.kind === 'direct') {
+      rememberConnectionTestTarget(
+        this.#state,
+        normalized.connectionTestTarget ?? normalized.replyTarget,
+      );
+    }
 
     const key = `${kind}:${conversationId}`;
     const pending = this.#pendingInteractions.get(key);
+    const text = cleanText(normalized.content);
+    const commandRunner = isControlCommand(text)
+      ? runControlCommand
+      : (isModelCommand(text) ? runModelCommand : null);
+    if (commandRunner && (normalized.kind !== 'group' || normalized.addressed === true)) {
+      let task;
+      task = this.#processFastCommand(
+        normalized,
+        messageId,
+        key,
+        commandRunner,
+      ).finally(() => {
+        this.#acceptedMessageIds.delete(messageId);
+        this.#commandTasks.delete(task);
+      });
+      this.#commandTasks.add(task);
+      return task;
+    }
     const approval = this.#approvals.claimReply({
       key,
       actor: senderId,
@@ -191,9 +228,57 @@ export class TextHarnessBridge {
         pending.queue ? [pending.queue] : []
       )),
       ...this.#approvalTasks,
+      ...this.#commandTasks,
     ]);
   }
 
+  async #processFastCommand(message, messageId, key, runner) {
+    if (this.#state.hasSeen(messageId)) return;
+    await this.#state.markSeen(messageId);
+    this.#status.messagesReceived += 1;
+    this.#status.lastMessageAt = new Date().toISOString();
+    const target = message.replyTarget;
+    try {
+      const result = await runner(
+        cleanText(message.content),
+        this.#harness,
+        this.#state,
+        key,
+        {
+          signal: this.#signal,
+          hasImages: hasInboundImages(message),
+          pendingInteraction: this.#pendingInteractions.has(key)
+            || this.#approvals.hasPending(key),
+          control: { owner: this, key },
+        },
+      );
+      if (result?.stopped) {
+        await Promise.allSettled([
+          this.#cancelPendingInteraction(key),
+          this.#approvals.closeRoute(key),
+        ]);
+      }
+      for (const reply of result?.messages ?? [result?.message]) {
+        if (reply) await this.#bot.sendText(target, reply);
+      }
+      this.#status.lastError = null;
+    } catch (error) {
+      if (error?.code === 'turn-stopped' || this.#signal?.aborted) return;
+      this.#status.lastError = error?.message ?? String(error);
+      this.#logger.error?.(`[dsh-im:${this.#descriptor.key}] failed to process a command:`, error);
+      await this.#bot.sendText(target, '消息处理失败，请稍后重试。').catch(() => undefined);
+    }
+  }
+
+  sendConnectionTest(text) {
+    return sendRememberedConnectionTest({
+      state: this.#state,
+      text,
+      channelLabel: `${this.#descriptor.label}机器人`,
+      send: (target, message) => this.#bot.sendText(target, message),
+    });
+  }
+
   async #process(message, messageId, senderId, conversationKey, {
     alreadyRecorded = false,
   } = {}) {
@@ -231,6 +316,10 @@ export class TextHarnessBridge {
           '/workspacelist  列出工作区绝对路径',
           '/sessionlist [工作区序号或绝对路径]  列出会话 ID 和标题',
           '/session Session ID 或当前工作区序号  将当前聊天绑定到指定会话',
+          '/models  列出所有可用模型',
+          '/model [模型ID]  查看或切换当前会话模型',
+          '/stop  停止当前任务',
+          '/steer 补充指令  纠偏当前任务',
           '/status  检查连接状态',
           '/help  显示本帮助',
         ].join('\n'));
@@ -297,6 +386,7 @@ export class TextHarnessBridge {
         askOptions: {
           timeoutMs: this.#replyTimeoutMs,
           signal: this.#signal,
+          control: { owner: this, key: conversationKey },
           onUpdate: stream ? async (update) => {
             const progress = update.type === 'text' ? update.text
               : update.type === 'tool' ? `正在使用${update.name}…` : update.text;
@@ -328,6 +418,16 @@ export class TextHarnessBridge {
       this.#status.lastReplyAt = new Date().toISOString();
       this.#status.lastError = null;
     } catch (error) {
+      if (error?.code === 'turn-stopped') {
+        if (stream) {
+          try {
+            await stream.finish('已停止。');
+          } catch {
+            stream.cancel?.();
+          }
+        }
+        return;
+      }
       stream?.cancel?.();
       if (this.#signal?.aborted) return;
       this.#status.lastError = error?.message ?? String(error);

package/src/channels/shared/token-bot-controller.mjs

@@ -1,3 +1,5 @@
+import { connectionTestMessage } from './connection-test.mjs';
+
 function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
@@ -161,6 +163,25 @@ export class TokenBotController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error(`Unknown ${this.#descriptor.label} bot`);
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        const error = new Error(`${this.#descriptor.label}机器人尚未连接`);
+        error.code = 'test-target-unavailable';
+        throw error;
+      }
+      const cardLabel = `${config.name}（${this.#maskPlatformId(config.platformId)}）`;
+      await runtime.sendConnectionTest(connectionTestMessage(
+        cardLabel,
+        `${this.#descriptor.label}机器人`,
+      ));
+      return { sent: true };
+    });
+  }
+
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error(`Unknown ${this.#descriptor.label} bot`);

package/src/channels/shared/workspace-session.mjs

@@ -1,3 +1,5 @@
+import { withSessionBindingLock } from './session-binding-lock.mjs';
+
 export const WORKSPACE_SESSION_STALE = 'workspace-session-stale';
 
 function workspaceSession(harness, sessionId) {
@@ -7,6 +9,12 @@ function workspaceSession(harness, sessionId) {
   return Object.freeze({
     sessionId,
     sessionExists: (...args) => harness.sessionExists(sessionId, ...args),
+    models: (...args) => harness.getSessionModels(sessionId, ...args),
+    selectModel: (...args) => harness.selectSessionModel(sessionId, ...args),
+    isRunning: (...args) => harness.isSessionRunning(sessionId, ...args),
+    hasActiveTurn: (...args) => harness.hasActiveTurn(sessionId, ...args),
+    stopActiveTurn: (...args) => harness.stopActiveTurn(sessionId, ...args),
+    steerActiveTurn: (...args) => harness.steerActiveTurn(sessionId, ...args),
     ask: (...args) => harness.ask(sessionId, ...args),
   });
 }
@@ -40,16 +48,20 @@ export async function askInWorkspaceSession({
 }) {
   while (true) {
     try {
-      let sessionId = state.sessionFor(key);
-      let session = sessionId ? workspaceSession(harness, sessionId) : null;
-      if (!session || !(await sessionExists(session, existsOptions))) {
-        sessionId = await createSession(harness, createOptions);
-        if (await state.setSession(key, sessionId) === false) continue;
-        session = workspaceSession(harness, sessionId);
-      }
+      const binding = await withSessionBindingLock(state, key, async () => {
+        let sessionId = state.sessionFor(key);
+        let session = sessionId ? workspaceSession(harness, sessionId) : null;
+        if (!session || !(await sessionExists(session, existsOptions))) {
+          sessionId = await createSession(harness, createOptions);
+          if (await state.setSession(key, sessionId) === false) return null;
+          session = workspaceSession(harness, sessionId);
+        }
+        return { sessionId, session };
+      });
+      if (!binding) continue;
       return {
-        sessionId,
-        answer: await session.ask(content ?? text, askOptions),
+        sessionId: binding.sessionId,
+        answer: await binding.session.ask(content ?? text, askOptions),
       };
     } catch (error) {
       if (error?.code !== WORKSPACE_SESSION_STALE) throw error;

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

@@ -1,3 +1,4 @@
+import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { deriveSlackBotIdentity, maskSlackBotId } from './config-store.mjs';
 import { inspectSlackCredentials } from './slack-api.mjs';
 import { SLACK_DESCRIPTOR } from './slack-bridge.mjs';
@@ -168,6 +169,24 @@ export class SlackController {
     return this.status();
   }
 
+  async sendConnectionTest(botId) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown Slack bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendConnectionTest !== 'function') {
+        const error = new Error('Slack机器人尚未连接');
+        error.code = 'test-target-unavailable';
+        throw error;
+      }
+      await runtime.sendConnectionTest(connectionTestMessage(
+        `${config.name}（${maskSlackBotId(config.platformId)}）`,
+        'Slack机器人',
+      ));
+      return { sent: true };
+    });
+  }
+
   async deleteBot(botId) {
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown Slack bot');

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

@@ -83,6 +83,7 @@ export function normalizeSlackEvent(payload, botUserId, { loadFile = async () =>
       recipientUserId: String(event.user),
       recipientTeamId: String(event.user_team ?? payload.team_id ?? ''),
     },
+    connectionTestTarget: { channelId: String(event.channel) },
   };
 }
 
@@ -293,6 +294,15 @@ export class SlackRuntime {
     return structuredClone(this.#status);
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#bridge) {
+      const error = new Error('Slack bot is not connected');
+      error.code = 'test-target-unavailable';
+      throw error;
+    }
+    return this.#bridge.sendConnectionTest(text);
+  }
+
   async start() {
     if (this.#status.ready && this.#socket) return this.status;
     if (this.#starting) return this.#starting;

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

@@ -111,6 +111,7 @@ export function normalizeTelegramUpdate(update, { botId, username, loadFile = as
       replyToMessageId: messageId,
       messageThreadId,
     },
+    connectionTestTarget: { chatId, messageThreadId },
   };
 }
 
@@ -229,6 +230,15 @@ export class TelegramRuntime {
     return structuredClone(this.#status);
   }
 
+  async sendConnectionTest(text) {
+    if (!this.#status.ready || !this.#bridge) {
+      const error = new Error('Telegram bot is not connected');
+      error.code = 'test-target-unavailable';
+      throw error;
+    }
+    return this.#bridge.sendConnectionTest(text);
+  }
+
   async start() {
     if (this.#status.ready && this.#pollTask) return this.status;
     if (this.#starting) return this.#starting;