fix(runtime): make Telegram bot connections operational

apps/desktop/src/main/__tests__/runtime-host-bot-session-adapter.test.ts

@@ -45,6 +45,7 @@ test('creates an explore Session through the Host-owned default model route', as
     {
       sessionId: 'bot-session-1',
       workspace: { kind: 'project', projectId: 'project-1' },
+      mode: 'bot_chat',
       name: 'Telegram conversation',
       labels: ['bot', 'telegram'],
       modelTarget: { kind: 'default' },

apps/desktop/src/main/bot-incoming-main.ts

@@ -9,7 +9,7 @@ import {
   nonTextMessageAck,
   plaintextHelpReply,
 } from '@maka/core/bot-events';
-import { generalizedErrorMessage } from '@maka/core/redaction';
+import { generalizedErrorMessage, redactSecrets } from '@maka/core/redaction';
 import type { BotIncomingMessage, BotRegistry, BotReplyStream } from '@maka/runtime/bots';
 import type { BotSessionAdapter, BotSessionTurnResult } from './bot-session-adapter.js';
 import { isBotSessionUnavailableError } from './bot-session-adapter.js';
@@ -205,6 +205,7 @@ export function createBotIncomingMainService(deps: BotIncomingMainServiceDeps):
   ): Promise<void> {
     if (closed) return;
     let replyStream: BotReplyStream | null = null;
+    let processingStage = 'command-routing';
     // PR-BOT-EPHEMERAL-REPLY-0: TTL for system notices (help / reset ack /
     // fallback errors). Five minutes is long enough for the user to read
     // and process the notice on mobile; short enough that bot DMs do not
@@ -248,13 +249,15 @@ export function createBotIncomingMainService(deps: BotIncomingMainServiceDeps):
     let sessionId = botConversationSessions.get(conversationKey);
     try {
       if (!sessionId) {
+        processingStage = 'session-create';
         sessionId = await createBotConversationSession(
           conversationKey,
           message,
           SYSTEM_NOTICE_TTL_MS,
         );
         if (!sessionId) return;
       } else {
+        processingStage = 'session-prepare';
         let rebound = false;
         try {
           const permissionModeOk = await ensureBotSessionExploreMode(
@@ -285,6 +288,7 @@ export function createBotIncomingMainService(deps: BotIncomingMainServiceDeps):
       }
 
       const turnId = randomUUID();
+      processingStage = 'turn-start';
       const replyOptions = message.sourceMessageId
         ? { replyToMessageId: message.sourceMessageId }
         : undefined;
@@ -344,6 +348,7 @@ export function createBotIncomingMainService(deps: BotIncomingMainServiceDeps):
       // bridge layer drops the field for non-Telegram platforms / multi-chunk
       // continuation pieces.
       if (reply.trim()) {
+        processingStage = 'reply-send';
         // Actual agent reply: NO ephemeral TTL. The answer must stay
         // visible — auto-deleting it would defeat the bot's purpose.
         const sent = replyStream
@@ -370,6 +375,12 @@ export function createBotIncomingMainService(deps: BotIncomingMainServiceDeps):
     } catch (error) {
       await replyStream?.abort().catch(() => {});
       if (closed) return;
+      const errorName = error instanceof Error ? error.name : typeof error;
+      const errorCode = readErrorCode(error);
+      const errorDetail = redactSecrets(error instanceof Error ? error.message : String(error));
+      console.error(
+        `[bot-incoming] conversation processing failed: stage=${processingStage} name=${errorName} code=${errorCode ?? 'unknown'} detail=${errorDetail}`,
+      );
       const detail = isSessionWorkspaceUnavailableError(error)
         ? '工作目录不可用，请在桌面端选择有效目录后重试'
         : generalizedErrorMessage(error, '机器人对话处理失败');
@@ -412,3 +423,9 @@ function botReply(result: BotSessionTurnResult): string {
   if (result.kind === 'errored') return `Maka 处理失败：${result.reason}`;
   return result.text;
 }
+
+function readErrorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object' || !('code' in error)) return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === 'string' || typeof code === 'number' ? String(code) : undefined;
+}

apps/desktop/src/main/runtime-host-bot-session-adapter.ts

@@ -54,6 +54,7 @@ export function createRuntimeHostBotSessionAdapter(
         session = await deps.client.createSession({
           sessionId,
           workspace: target.workspace,
+          mode: 'bot_chat',
           name: input.name,
           labels: [...input.labels],
           modelTarget: { kind: 'default' },

apps/desktop/src/main/settings-bots-ipc-main.ts

@@ -87,16 +87,25 @@ export function registerSettingsBotsIpc(
     });
     return toSettingsTestResult(provider, result);
   });
-  deps.ipcMain.handle('settings:bots:listStatuses', () =>
-    tryResult(async () => deps.botRegistry.allStatuses(), 'BOTS_STATUS_FAILED'),
-  );
+  deps.ipcMain.handle('settings:bots:listStatuses', () => deps.botRegistry.allStatuses());
   deps.ipcMain.handle('settings:bots:restart', (_event, provider: BotProvider) =>
-    tryResult(async () => {
-      await deps.botRegistry.applySettings(
-        (await deps.settingsStore.get()).botChat,
+    (async () => {
+      const settings = await deps.settingsStore.get();
+      const status = await deps.botRegistry.restart(
+        provider,
+        settings.botChat.channels[provider],
       );
-      return deps.botRegistry.getStatus(provider);
-    }, 'BOTS_RESTART_FAILED'),
+      if (!status.running) {
+        const reason = status.reason ?? 'unknown';
+        console.error(
+          `[BotRegistry] ${provider} restart did not enter listening: ${reason}`,
+        );
+        // The renderer intentionally hides unmapped raw status reasons. Reject
+        // here so diagnostics retain the actionable, already-generalized cause.
+        throw new Error(`${provider} listener startup failed: ${reason}`);
+      }
+      return status;
+    })(),
   );
   deps.ipcMain.handle(
     'settings:bots:onboarding:start',

packages/core/src/__tests__/bot-events.test.ts

@@ -33,6 +33,7 @@ describe('bot event contract', () => {
   test('recognizes only exact plaintext commands in direct messages', () => {
     assert.equal(isPlaintextResetCommand({ isGroup: false, text: '  RESET  ' }), true);
     assert.equal(isPlaintextHelpCommand({ isGroup: false, text: '帮助' }), true);
+    assert.equal(isPlaintextHelpCommand({ isGroup: false, text: ' /START ' }), true);
     assert.equal(isPlaintextHelpCommand({ isGroup: true, text: 'help' }), false);
     assert.equal(isPlaintextHelpCommand({ isGroup: false, text: 'please help' }), false);
     assert.equal(isPlaintextHelpCommand({ isGroup: false, text: '   ' }), false);

packages/core/src/bot-events.ts

@@ -142,6 +142,7 @@ export function isPlaintextResetCommand(
 }
 
 export const BOT_PLAINTEXT_HELP_COMMANDS: ReadonlyArray<string> = Object.freeze([
+  '/start',
   'help',
   '/help',
   '?',

packages/core/src/explore-agent.ts

@@ -22,6 +22,11 @@ export interface SessionStartModeSpec {
 }
 
 export const SESSION_START_MODE_SPECS = {
+  bot_chat: {
+    name: 'Bot conversation',
+    labels: ['mode:bot_chat'],
+    permissionMode: 'explore',
+  },
   deep_research: {
     name: 'Deep Research',
     labels: ['mode:deep_research'],

packages/runtime/src/bots/__tests__/base-adapter.test.ts

@@ -47,6 +47,10 @@ describe('BaseBotAdapter', () => {
       botSettingsRequireRestart(base, { ...base, domain: 'https://bot.example.test' }),
       true,
     );
+    assert.equal(
+      botSettingsRequireRestart(base, { ...base, proxyUrl: 'http://127.0.0.1:7897' }),
+      true,
+    );
 
     const adapter = new TestAdapter('telegram', { ...base, enabled: true, token: 'old-token' });
     assert.deepEqual(adapter.updateSettings({ ...base, enabled: true, token: 'old-token' }), {

packages/runtime/src/bots/__tests__/bot-registry.test.ts

@@ -70,6 +70,33 @@ describe('BotRegistry', () => {
     assert.equal(registry.getStatus('wecom').readiness, 'scaffolded');
   });
 
+  test('restart force-starts a stopped bridge even when settings are unchanged', async () => {
+    const statuses: BotStatus[] = [];
+    const registry = new BotRegistry({
+      onIncomingMessage: () => {},
+      onStatusChange: (status) => statuses.push(status),
+    });
+    const channel = {
+      ...createDefaultBotChannel('wecom'),
+      enabled: true,
+      token: '',
+      appId: undefined,
+      appSecret: undefined,
+    };
+
+    await registry.applySettings(settingsWith({ wecom: channel }));
+    const beforeRestart = statuses.length;
+    const status = await registry.restart('wecom', channel);
+
+    assert.equal(status.running, false);
+    assert.equal(status.reason, 'no-credentials');
+    assert.equal(statuses.length > beforeRestart, true);
+    assert.equal(
+      statuses.slice(beforeRestart).some((entry) => entry.platform === 'wecom'),
+      true,
+    );
+  });
+
   test('stopAll waits behind any pending applySettings call and clears bridges', async () => {
     const registry = new BotRegistry({
       onIncomingMessage: () => {},

packages/runtime/src/bots/__tests__/proxied-fetch.test.ts

@@ -87,6 +87,31 @@ function startStreamingProxy(): Promise<{
 }
 
 describe('proxiedFetch', () => {
+  test('uses a per-request proxy URL when no global proxy is active', async () => {
+    const proxy = await startStreamingProxy();
+    setActiveProxy(null);
+    try {
+      const response = await withTimeout(
+        proxiedFetch('http://example.test/channel-proxy', {
+          timeoutMs: 0,
+          proxyUrl: `http://127.0.0.1:${proxy.port}`,
+        }),
+        5_000,
+        'proxiedFetch did not use the per-request proxy URL',
+      );
+      assert.equal(response.status, 200);
+      assert.ok(response.body);
+      const reader = response.body.getReader();
+      const first = await withTimeout(reader.read(), 5_000, 'proxy body was not readable');
+      assert.equal(Buffer.from(first.value ?? []).toString(), 'hello world');
+      proxy.sendTail();
+      await reader.cancel();
+    } finally {
+      setActiveProxy(null);
+      await proxy.close();
+    }
+  });
+
   test('returns a streaming proxied response at headers, before body EOF', async () => {
     const proxy = await startStreamingProxy();
     setActiveProxy({

packages/runtime/src/bots/base-adapter.ts

@@ -76,6 +76,7 @@ export function botSettingsRequireRestart(
     previous.appId !== next.appId ||
     previous.appSecret !== next.appSecret ||
     previous.domain !== next.domain ||
-    previous.webhookUrl !== next.webhookUrl
+    previous.webhookUrl !== next.webhookUrl ||
+    previous.proxyUrl !== next.proxyUrl
   );
 }

packages/runtime/src/bots/bot-registry.ts

@@ -48,6 +48,27 @@ export class BotRegistry extends EventEmitter {
     return next;
   }
 
+  /** Force a provider restart even when its persisted settings are unchanged. */
+  async restart(platform: BotPlatform, settings: BotChannelSettings): Promise<BotStatus> {
+    const restart = async (): Promise<BotStatus> => {
+      const existing = this.bridges.get(platform);
+      if (existing) {
+        await existing.stop().catch(() => {});
+        this.detach(existing);
+        this.bridges.delete(platform);
+      }
+      this.statuses.delete(platform);
+      await this.reconcileOne(platform, settings);
+      return this.getStatus(platform);
+    };
+    const next = this.applyQueue.then(restart, restart);
+    this.applyQueue = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  }
+
   getStatus(platform: BotPlatform): BotStatus {
     return (
       this.bridges.get(platform)?.getStatus() ??
@@ -134,18 +155,7 @@ export class BotRegistry extends EventEmitter {
       ).updateSettings;
       if (update && !update.call(existing, settings).needsRestart) return;
       await existing.stop().catch(() => {});
-      // Drop our 'message' / 'statusChange' listeners on the old
-      // bridge before dereferencing it. Some bridges (Discord
-      // gateway, WeChat poll) hold async tasks that can still emit
-      // after `stop()` returns; without removeAllListeners those
-      // emissions would race-call onIncomingMessage / onStatusChange
-      // against a bridge the registry already considers gone.
-      try {
-        (existing as BotBridge & EventEmitter).removeAllListeners('message');
-        (existing as BotBridge & EventEmitter).removeAllListeners('statusChange');
-      } catch {
-        // best-effort — non-EventEmitter bridges don't have listeners to clear.
-      }
+      this.detach(existing);
     }
     this.statuses.delete(platform);
 
@@ -174,6 +184,18 @@ export class BotRegistry extends EventEmitter {
       );
   }
 
+  private detach(bridge: BotBridge): void {
+    // Some bridges retain async tasks after stop(); detach registry listeners
+    // before dereferencing them so stale emissions cannot race the replacement.
+    try {
+      const emitter = bridge as BotBridge & EventEmitter;
+      emitter.removeAllListeners('message');
+      emitter.removeAllListeners('statusChange');
+    } catch {
+      // Non-EventEmitter bridges have no listeners to clear.
+    }
+  }
+
   private wire(bridge: BotBridge): void {
     const emitter = bridge as BotBridge & EventEmitter;
     emitter.on('message', (message: BotIncomingMessage) => this.deps.onIncomingMessage(message));

packages/runtime/src/bots/bot-test.ts

@@ -121,7 +121,11 @@ async function testTelegram(channel: BotChannelSettings): Promise<BotTestResult>
   const base = `https://api.telegram.org/bot${channel.token}`;
   try {
     const me = await (
-      await proxiedFetch(`${base}/getMe`, { method: 'GET', timeoutMs: BOT_TEST_TIMEOUT_MS })
+      await proxiedFetch(`${base}/getMe`, {
+        method: 'GET',
+        timeoutMs: BOT_TEST_TIMEOUT_MS,
+        proxyUrl: channel.proxyUrl,
+      })
     ).json();
     if (!me.ok) return { ok: false, error: me.description ?? 'Invalid bot token' };
     return {

packages/runtime/src/bots/proxied-fetch.ts

@@ -1,3 +1,4 @@
+import type { ProxySettings } from '@maka/core/settings/network-settings';
 import { fetch, type Dispatcher, type RequestInit as UndiciRequestInit } from 'undici';
 import { matchesBypassList } from '../network/bypass-matcher.js';
 import { buildProxyDispatcher } from '../network/proxy-dispatcher.js';
@@ -12,6 +13,8 @@ export type ProxiedFetchInit = Omit<
 > & {
   signal?: AbortSignal | null;
   timeoutMs?: number;
+  /** Per-channel proxy override (for example Telegram's saved proxy URL). */
+  proxyUrl?: string;
 };
 
 export async function proxiedFetch(
@@ -20,12 +23,12 @@ export async function proxiedFetch(
 ): Promise<Response> {
   const url =
     typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
-  const proxy = resolveActiveProxy();
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, signal, proxyUrl, ...fetchInit } = init;
+  const proxy = proxyUrl?.trim() ? proxySettingsFromUrl(proxyUrl) : resolveActiveProxy();
   let dispatcher: Dispatcher | undefined;
   if (proxy && !matchesBypassList(new URL(url).hostname, proxy.bypassList)) {
     dispatcher = buildProxyDispatcher(proxy) as Dispatcher;
   }
-  const { timeoutMs = DEFAULT_TIMEOUT_MS, signal, ...fetchInit } = init;
   const timeoutEnabled = timeoutMs > 0;
   const controller = new AbortController();
   const requestSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
@@ -91,6 +94,32 @@ export async function proxiedFetch(
   return response;
 }
 
+function proxySettingsFromUrl(value: string): ProxySettings {
+  const url = new URL(value);
+  const type =
+    url.protocol === 'socks5:'
+      ? 'socks5'
+      : url.protocol === 'https:'
+        ? 'https'
+        : url.protocol === 'http:'
+          ? 'http'
+          : undefined;
+  if (!type) throw new Error(`Unsupported proxy protocol: ${url.protocol}`);
+  const port = Number(url.port || (type === 'https' ? 443 : type === 'socks5' ? 1080 : 80));
+  if (!url.hostname || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('Invalid proxy URL');
+  }
+  return {
+    enabled: true,
+    type,
+    host: url.hostname,
+    port,
+    ...(url.username ? { username: decodeURIComponent(url.username) } : {}),
+    ...(url.password ? { password: decodeURIComponent(url.password) } : {}),
+    bypassList: [],
+  };
+}
+
 Object.defineProperty(proxiedFetch, FETCH_PROXY_SNAPSHOT, {
   get: resolveActiveProxy,
   enumerable: false,