@pixelbyte-software/pixcode 1.53.3 → 1.53.5

package/server/services/telegram/control-center.js

@@ -4,11 +4,27 @@ import { apiKeysDb, telegramLinksDb } from '../../database/db.js';
 import { getProjects } from '../../projects.js';
 import { getStaticProviderModels } from '../model-registry.js';
 
+import {
+  TELEGRAM_CONTROL_SCOPES,
+  TELEGRAM_PROVIDERS,
+  buildTelegramAgentPrompt,
+  classifyTelegramIntent,
+  clearTelegramConfirmation,
+  consumeTelegramConfirmation,
+  createTelegramConfirmation,
+  enqueueTelegramJob,
+  resolveTelegramModel,
+  resolveTelegramProvider,
+  retryWithBackoff,
+  runTelegramTool,
+  splitTelegramText,
+} from './telegram-gateway.js';
 import { SUPPORTED_LANGUAGES, t } from './translations.js';
 
-const PROVIDERS = ['claude', 'cursor', 'codex', 'gemini', 'qwen', 'opencode'];
+const PROVIDERS = TELEGRAM_PROVIDERS;
 const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
 const CALLBACK_TTL_MS = 10 * 60 * 1000;
+const MAX_CALLBACK_ACTIONS = 1000;
 const MAX_TELEGRAM_TEXT = 3600;
 const callbackActions = new Map();
 const runMonitors = new Map();
@@ -94,7 +110,23 @@ export function updateTelegramControlState(userId, patch) {
   return telegramLinksDb.updateControlState(userId, patch);
 }
 
+function pruneCallbackActions() {
+  const now = Date.now();
+  for (const [id, entry] of callbackActions.entries()) {
+    if (entry.expiresAt < now) {
+      callbackActions.delete(id);
+    }
+  }
+
+  while (callbackActions.size > MAX_CALLBACK_ACTIONS) {
+    const oldestId = callbackActions.keys().next().value;
+    if (!oldestId) break;
+    callbackActions.delete(oldestId);
+  }
+}
+
 function registerAction(action, payload = {}) {
+  pruneCallbackActions();
   const id = crypto.randomBytes(8).toString('hex');
   callbackActions.set(id, {
     action,
@@ -113,7 +145,11 @@ function readAction(data) {
     callbackActions.delete(id);
     return null;
   }
-  return entry;
+  return { id, ...entry };
+}
+
+function forgetAction(id) {
+  if (id) callbackActions.delete(id);
 }
 
 function button(text, action, payload = {}) {
@@ -133,27 +169,44 @@ async function send(bot, chatId, text, options = {}) {
     disable_web_page_preview: true,
     ...telegramOptions,
   };
-  const messageText = truncate(text);
+  const chunks = splitTelegramText(text, MAX_TELEGRAM_TEXT);
+  const [firstChunk = ''] = chunks;
+  let startIndex = 0;
   if (editMessageId && typeof bot.editMessageText === 'function') {
     try {
-      return await bot.editMessageText(messageText, {
+      const edited = await bot.editMessageText(firstChunk, {
         chat_id: chatId,
         message_id: editMessageId,
         ...extra,
       });
+      startIndex = 1;
+      for (const chunk of chunks.slice(startIndex)) {
+        await send(bot, chatId, chunk, telegramOptions);
+      }
+      return edited;
     } catch (err) {
       const description = err?.response?.body?.description || err?.message || '';
-      if (/message is not modified/i.test(description)) return null;
+      if (/message is not modified/i.test(description)) {
+        startIndex = 1;
+        for (const chunk of chunks.slice(startIndex)) {
+          await send(bot, chatId, chunk, telegramOptions);
+        }
+        return null;
+      }
       console.warn('[telegram-control] editMessageText failed:', description || err);
     }
   }
-  try {
-    return await bot.sendMessage(chatId, messageText, extra);
-  } catch {
-    const fallback = { ...extra };
-    delete fallback.parse_mode;
-    return bot.sendMessage(chatId, messageText, fallback);
+  let result = null;
+  for (const chunk of chunks.slice(startIndex)) {
+    try {
+      result = await bot.sendMessage(chatId, chunk, extra);
+    } catch {
+      const fallback = { ...extra };
+      delete fallback.parse_mode;
+      result = await bot.sendMessage(chatId, chunk, fallback);
+    }
   }
+  return result;
 }
 
 function localApiBase() {
@@ -165,19 +218,35 @@ function getOrCreateTelegramApiKey(userId) {
   const existing = apiKeysDb
     .getApiKeys(userId)
     .find((key) => key.key_name === 'Telegram Control' && Boolean(key.is_active));
-  if (existing?.api_key) return existing.api_key;
-  return apiKeysDb.createApiKey(userId, 'Telegram Control').apiKey;
+  if (existing?.api_key) {
+    const existingScopes = apiKeysDb.normalizeScopes(existing.scopes || []);
+    const nextScopes = apiKeysDb.normalizeScopes([...existingScopes, ...TELEGRAM_CONTROL_SCOPES]);
+    const hasAllScopes = TELEGRAM_CONTROL_SCOPES.every((scope) => existingScopes.includes(scope));
+    if (!hasAllScopes || nextScopes.length !== existingScopes.length) {
+      apiKeysDb.updateApiKeyScopes(userId, existing.id, nextScopes);
+    }
+    return existing.api_key;
+  }
+  return apiKeysDb.createApiKey(userId, 'Telegram Control', TELEGRAM_CONTROL_SCOPES).apiKey;
 }
 
 async function localApi(userId, path, { method = 'GET', body } = {}) {
   const apiKey = getOrCreateTelegramApiKey(userId);
-  const response = await fetch(`${localApiBase()}${path}`, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      'X-API-Key': apiKey,
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
+  const response = await retryWithBackoff(async () => {
+    const res = await fetch(`${localApiBase()}${path}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': apiKey,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if ([408, 429, 500, 502, 503, 504].includes(res.status)) {
+      const error = new Error(`HTTP ${res.status}`);
+      error.status = res.status;
+      throw error;
+    }
+    return res;
   });
   const data = await response.json().catch(() => ({}));
   if (!response.ok) {
@@ -470,6 +539,39 @@ function extractAssistantText(response) {
   return chunks.join('\n\n').trim();
 }
 
+function confirmationLabel(lang, action, payload = {}) {
+  if (action === 'install_provider') {
+    return t(lang, 'control.confirmInstall', { provider: payload.provider || '' });
+  }
+  if (action === 'run_cancel') {
+    return t(lang, 'control.confirmCancelRun', { runId: payload.runId || '' });
+  }
+  return t(lang, 'control.confirmationRequired');
+}
+
+async function requestConfirmation({ bot, chatId, link, action, payload = {}, editMessageId }) {
+  const lang = languageFor(link);
+  const pending = createTelegramConfirmation(link.user_id, action, payload);
+  await send(bot, chatId, confirmationLabel(lang, action, payload), {
+    editMessageId,
+    reply_markup: {
+      inline_keyboard: [[
+        button(t(lang, 'control.button.confirm'), 'confirm_action', { id: pending.id }),
+        button(t(lang, 'control.button.cancel'), 'cancel_confirmation', { id: pending.id }),
+      ]],
+    },
+  });
+  return { ok: false, requiresConfirmation: true };
+}
+
+async function sendToolFailure({ bot, chatId, link, result, editMessageId }) {
+  const lang = languageFor(link);
+  const message = result?.message === 'REMOTE_CONTROL_DISABLED'
+    ? t(lang, 'control.disabled')
+    : (result?.message || t(lang, 'error.generic'));
+  await send(bot, chatId, message, { editMessageId });
+}
+
 async function runAgent({ bot, chatId, link, prompt }) {
   const lang = languageFor(link);
   const state = getState(link.user_id);
@@ -483,28 +585,41 @@ async function runAgent({ bot, chatId, link, prompt }) {
     return;
   }
 
+  const provider = resolveTelegramProvider(state);
+  const model = resolveTelegramModel(state);
   if (state.progressMode !== 'final') {
     await send(bot, chatId, t(lang, 'control.agentStarted', {
-      provider: state.selectedProvider,
+      provider,
       project: state.selectedProjectName || state.selectedProjectPath,
     }));
   }
 
-  const response = await localApi(link.user_id, '/api/agent', {
-    method: 'POST',
-    body: {
-      projectPath: state.selectedProjectPath,
-      provider: state.selectedProvider,
-      model: state.selectedModel || undefined,
-      message: prompt,
-      cleanup: false,
-      stream: false,
-    },
+  const result = await runTelegramTool({
+    userId: link.user_id,
+    action: 'run_agent',
+    retries: 0,
+    execute: () => localApi(link.user_id, '/api/agent', {
+      method: 'POST',
+      body: {
+        projectPath: state.selectedProjectPath,
+        provider,
+        model: model || undefined,
+        message: buildTelegramAgentPrompt(prompt, state),
+        cleanup: false,
+        stream: false,
+      },
+    }),
   });
+  if (!result.ok) {
+    await sendToolFailure({ bot, chatId, link, result });
+    return;
+  }
+
+  const response = result.data;
   const assistantText = extractAssistantText(response);
   const statusLine = response.success === false
     ? t(lang, 'control.agentFailed', { error: response.error || 'provider returned no answer' })
-    : t(lang, 'control.agentDone', { provider: state.selectedProvider, session: response.sessionId ? ` (${response.sessionId})` : '' });
+    : t(lang, 'control.agentDone', { provider, session: response.sessionId ? ` (${response.sessionId})` : '' });
   await send(bot, chatId, `${statusLine}\n\n${assistantText || response.error || t(lang, 'control.noAssistantText')}`);
 }
 
@@ -512,6 +627,10 @@ export async function runWorkflow({ bot, chatId, link, input }) {
   const lang = languageFor(link);
   const state = getState(link.user_id);
   const workflowId = state.selectedWorkflowId;
+  if (!state.remoteControlEnabled) {
+    await send(bot, chatId, t(lang, 'control.disabled'));
+    return;
+  }
   if (!workflowId) {
     await send(bot, chatId, t(lang, 'control.selectWorkflowFirst'));
     await showWorkflowMenu({ bot, chatId, link });
@@ -523,27 +642,178 @@ export async function runWorkflow({ bot, chatId, link, input }) {
     return;
   }
 
-  const run = await localApi(link.user_id, `/api/orchestration/workflows/${workflowId}/runs`, {
-    method: 'POST',
-    body: {
-      input,
-      metadata: {
-        projectId: state.selectedProjectName,
-        projectName: state.selectedProjectName,
-        projectPath: state.selectedProjectPath,
-        workspaceTarget: 'selected_project',
-        telegram: true,
-        preferredProvider: state.selectedProvider,
-        preferredModel: state.selectedModel,
+  const provider = resolveTelegramProvider(state);
+  const model = resolveTelegramModel(state);
+  const result = await runTelegramTool({
+    userId: link.user_id,
+    action: 'run_workflow',
+    execute: () => localApi(link.user_id, `/api/orchestration/workflows/${workflowId}/runs`, {
+      method: 'POST',
+      body: {
+        input,
+        metadata: {
+          projectId: state.selectedProjectName,
+          projectName: state.selectedProjectName,
+          projectPath: state.selectedProjectPath,
+          workspaceTarget: 'selected_project',
+          telegram: true,
+          preferredProvider: provider,
+          preferredModel: model,
+        },
       },
-    },
+    }),
   });
+  if (!result.ok) {
+    await sendToolFailure({ bot, chatId, link, result });
+    return;
+  }
+  const run = result.data;
   await send(bot, chatId, t(lang, 'control.workflowStarted', { runId: run.id, workflowId }));
   monitorWorkflowRun({ bot, chatId, link, runId: run.id }).catch((error) => {
     console.warn('[telegram-control] workflow monitor failed:', error?.message || error);
   });
 }
 
+async function cancelRun({ bot, chatId, link, runId, editMessageId, confirmed = false }) {
+  const lang = languageFor(link);
+  if (!runId) {
+    await send(bot, chatId, t(lang, 'control.cancelUsage'), { editMessageId });
+    return;
+  }
+  const state = getState(link.user_id);
+  if (state.remoteControlEnabled === false) {
+    await send(bot, chatId, t(lang, 'control.disabled'), { editMessageId });
+    return;
+  }
+  if (state.confirmationPolicy === 'strict' && !confirmed) {
+    await requestConfirmation({
+      bot,
+      chatId,
+      link,
+      action: 'run_cancel',
+      payload: { runId },
+      editMessageId,
+    });
+    return;
+  }
+
+  const result = await runTelegramTool({
+    userId: link.user_id,
+    action: 'run_cancel',
+    execute: () => localApi(link.user_id, `/api/orchestration/workflows/runs/${encodeURIComponent(runId)}/cancel`, {
+      method: 'POST',
+    }),
+  });
+  if (!result.ok) {
+    await sendToolFailure({ bot, chatId, link, result, editMessageId });
+    return;
+  }
+  const run = result.data;
+  await send(bot, chatId, t(lang, 'control.runStatus', { runId: run.id, status: run.status }), { editMessageId });
+}
+
+async function executeConfirmedAction({ bot, chatId, link, confirmation, editMessageId }) {
+  if (confirmation.action === 'install_provider') {
+    await startCliInstall({
+      bot,
+      chatId,
+      link,
+      provider: confirmation.payload?.provider,
+      editMessageId,
+      confirmed: true,
+    });
+    return true;
+  }
+  if (confirmation.action === 'run_cancel') {
+    await cancelRun({
+      bot,
+      chatId,
+      link,
+      runId: confirmation.payload?.runId,
+      editMessageId,
+      confirmed: true,
+    });
+    return true;
+  }
+  return false;
+}
+
+async function findProjectByQuery(query) {
+  const projects = await listProjects();
+  const needle = String(query || '').trim().toLocaleLowerCase('tr');
+  if (!needle) return null;
+  return projects.find((project) => {
+    const candidates = [project.name, project.displayName, project.fullPath, project.path]
+      .filter(Boolean)
+      .map((value) => String(value).toLocaleLowerCase('tr'));
+    return candidates.some((candidate) => candidate === needle || candidate.includes(needle));
+  }) || null;
+}
+
+async function handleRoutedIntent({ bot, chatId, link, text }) {
+  const state = getState(link.user_id);
+  const intent = classifyTelegramIntent(text, state);
+  if (!intent) return false;
+
+  if (intent.action === 'projects') {
+    await showProjectMenu({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'project_select_query') {
+    const project = await findProjectByQuery(intent.query);
+    const lang = languageFor(link);
+    if (!project) {
+      await send(bot, chatId, t(lang, 'control.projectNotFound', { query: intent.query }));
+      await showProjectMenu({ bot, chatId, link });
+      return true;
+    }
+    updateTelegramControlState(link.user_id, {
+      selectedProjectName: project.name,
+      selectedProjectPath: project.fullPath || project.path,
+    });
+    await showMainMenu({
+      bot,
+      chatId,
+      link,
+      notice: t(lang, 'control.projectSelected', {
+        project: project.displayName || project.name,
+        path: project.fullPath || project.path,
+      }),
+    });
+    return true;
+  }
+  if (intent.action === 'provider_menu') {
+    await showProviderMenu({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'provider_select') {
+    updateTelegramControlState(link.user_id, { selectedProvider: intent.provider, selectedModel: null });
+    await showModelMenu({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'model_menu') {
+    await showModelMenu({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'runs') {
+    await showRuns({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'approvals') {
+    await showApprovalQueue({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'workflows') {
+    await showWorkflowMenu({ bot, chatId, link });
+    return true;
+  }
+  if (intent.action === 'new_chat') {
+    await startNewChat({ bot, chatId, link });
+    return true;
+  }
+  return false;
+}
+
 async function fetchRun(userId, runId) {
   return localApi(userId, `/api/orchestration/workflows/runs/${runId}`);
 }
@@ -608,18 +878,49 @@ async function monitorWorkflowRun({ bot, chatId, link, runId }) {
   }
 }
 
-export async function startCliInstall({ bot, chatId, link, provider }) {
+export async function startCliInstall({ bot, chatId, link, provider, editMessageId, confirmed = false }) {
   const lang = languageFor(link);
-  const data = await localApi(link.user_id, `/api/providers/${provider}/install`, { method: 'POST' });
+  if (!PROVIDERS.includes(provider)) {
+    await send(bot, chatId, t(lang, 'control.providerAuthFallback'), { editMessageId });
+    return;
+  }
+  const state = getState(link.user_id);
+  if (state.remoteControlEnabled === false) {
+    await send(bot, chatId, t(lang, 'control.disabled'), { editMessageId });
+    return;
+  }
+  if (state.confirmationPolicy === 'strict' && !confirmed) {
+    await requestConfirmation({
+      bot,
+      chatId,
+      link,
+      action: 'install_provider',
+      payload: { provider },
+      editMessageId,
+    });
+    return;
+  }
+
+  const result = await runTelegramTool({
+    userId: link.user_id,
+    action: 'install_provider',
+    execute: () => localApi(link.user_id, `/api/providers/${provider}/install`, { method: 'POST' }),
+  });
+  if (!result.ok) {
+    await sendToolFailure({ bot, chatId, link, result, editMessageId });
+    return;
+  }
+
+  const data = result.data;
   if (data?.manual) {
-    await send(bot, chatId, t(lang, 'control.manualInstall', { provider, manual: data.manual }));
+    await send(bot, chatId, t(lang, 'control.manualInstall', { provider, manual: data.manual }), { editMessageId });
     return;
   }
   await send(bot, chatId, t(lang, 'control.installStarted', {
     provider,
     jobId: data.jobId,
     command: data.installCmd || 'internal installer',
-  }));
+  }), { editMessageId });
 }
 
 async function showInstallMenu({ bot, chatId, link, editMessageId }) {
@@ -801,16 +1102,13 @@ async function handleCommand({ bot, chatId, link, text }) {
       await send(bot, chatId, t(lang, 'control.cancelUsage'));
       return true;
     }
-    const run = await localApi(link.user_id, `/api/orchestration/workflows/runs/${encodeURIComponent(argText)}/cancel`, {
-      method: 'POST',
-    });
-    await send(bot, chatId, t(lang, 'control.runStatus', { runId: run.id, status: run.status }));
+    await cancelRun({ bot, chatId, link, runId: argText });
     return true;
   }
   return false;
 }
 
-export async function handleTelegramControlMessage({ bot, msg, link }) {
+async function handleTelegramControlMessageInternal({ bot, msg, link }) {
   const chatId = msg.chat.id;
   const text = String(msg.text || '').trim();
   if (!text) return false;
@@ -826,8 +1124,10 @@ export async function handleTelegramControlMessage({ bot, msg, link }) {
 
   if (await handleAwaitingInput({ bot, chatId, link, text })) return true;
   if (await handleCommand({ bot, chatId, link, text })) return true;
+  if (await handleRoutedIntent({ bot, chatId, link, text })) return true;
 
   const state = getState(link.user_id);
+  if (state.routerEnabled === false) return false;
   if (!state.remoteControlEnabled) {
     await send(bot, chatId, t(languageFor(link), 'control.disabled'));
     return true;
@@ -837,6 +1137,20 @@ export async function handleTelegramControlMessage({ bot, msg, link }) {
   return true;
 }
 
+export async function handleTelegramControlMessage(args) {
+  const chatId = args?.msg?.chat?.id;
+  if (!chatId) return false;
+  return enqueueTelegramJob(chatId, async () => {
+    try {
+      return await handleTelegramControlMessageInternal(args);
+    } catch (error) {
+      console.error('[telegram-control] message handler failed:', error);
+      await send(args.bot, chatId, t(languageFor(args.link), 'error.generic')).catch(() => {});
+      return true;
+    }
+  });
+}
+
 async function showRunDetail({ bot, chatId, link, runId, editMessageId }) {
   const lang = languageFor(link);
   const run = await fetchRun(link.user_id, runId);
@@ -851,7 +1165,7 @@ async function showRunDetail({ bot, chatId, link, runId, editMessageId }) {
   });
 }
 
-export async function handleTelegramControlCallback({ bot, query, link }) {
+async function handleTelegramControlCallbackInternal({ bot, query, link }) {
   const chatId = query.message?.chat?.id;
   if (!chatId) return;
   const editMessageId = query.message?.message_id;
@@ -865,6 +1179,32 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
   await bot.answerCallbackQuery(query.id).catch(() => {});
 
   const { action, payload } = entry;
+  if (action === 'confirm_action') {
+    forgetAction(entry.id);
+    const lang = languageFor(link);
+    const result = consumeTelegramConfirmation(link.user_id, payload.id);
+    if (!result.ok) {
+      await send(bot, chatId, t(lang, result.reason === 'expired'
+        ? 'control.confirmationExpired'
+        : 'control.confirmationMissing'), { editMessageId });
+      return;
+    }
+    if (await executeConfirmedAction({
+      bot,
+      chatId,
+      link,
+      confirmation: result.confirmation,
+      editMessageId,
+    })) return;
+    await send(bot, chatId, t(lang, 'error.generic'), { editMessageId });
+    return;
+  }
+  if (action === 'cancel_confirmation') {
+    forgetAction(entry.id);
+    clearTelegramConfirmation(link.user_id, payload.id);
+    await send(bot, chatId, t(languageFor(link), 'control.confirmationCanceled'), { editMessageId });
+    return;
+  }
   if (action === 'menu') return showMainMenu({ bot, chatId, link, editMessageId });
   if (action === 'projects') return showProjectMenu({ bot, chatId, link, editMessageId });
   if (action === 'providers') return showProviderMenu({ bot, chatId, link, editMessageId });
@@ -930,20 +1270,26 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
   }
   if (action === 'run_detail') return showRunDetail({ bot, chatId, link, runId: payload.runId, editMessageId });
   if (action === 'run_cancel') {
-    const run = await localApi(link.user_id, `/api/orchestration/workflows/runs/${encodeURIComponent(payload.runId)}/cancel`, {
-      method: 'POST',
-    });
-    await send(bot, chatId, t(languageFor(link), 'control.runStatus', { runId: run.id, status: run.status }), { editMessageId });
+    await cancelRun({ bot, chatId, link, runId: payload.runId, editMessageId });
     return;
   }
   if (action === 'approval_decide') {
-    const result = await localApi(link.user_id, `/api/orchestration/workflows/approvals/${encodeURIComponent(payload.approvalId)}`, {
-      method: 'POST',
-      body: {
-        allow: payload.allow === true,
-        source: 'telegram',
-      },
+    const toolResult = await runTelegramTool({
+      userId: link.user_id,
+      action: 'approval_decide',
+      execute: () => localApi(link.user_id, `/api/orchestration/workflows/approvals/${encodeURIComponent(payload.approvalId)}`, {
+        method: 'POST',
+        body: {
+          allow: payload.allow === true,
+          source: 'telegram',
+        },
+      }),
     });
+    if (!toolResult.ok) {
+      await sendToolFailure({ bot, chatId, link, result: toolResult, editMessageId });
+      return;
+    }
+    const result = toolResult.data;
     const lang = languageFor(link);
     await send(bot, chatId, t(lang, 'control.approvalDecided', {
       approvalId: payload.approvalId,
@@ -952,7 +1298,7 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
     }), { editMessageId });
     return showApprovalQueue({ bot, chatId, link });
   }
-  if (action === 'install_provider') return startCliInstall({ bot, chatId, link, provider: payload.provider });
+  if (action === 'install_provider') return startCliInstall({ bot, chatId, link, provider: payload.provider, editMessageId });
   if (action === 'auth_provider') {
     await send(bot, chatId, `${payload.provider} login:\n${AUTH_HELP[payload.provider] || t(languageFor(link), 'control.providerAuthFallback')}`, { editMessageId });
     return;
@@ -977,3 +1323,18 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
     });
   }
 }
+
+export async function handleTelegramControlCallback(args) {
+  const chatId = args?.query?.message?.chat?.id;
+  if (!chatId) return;
+  return enqueueTelegramJob(chatId, async () => {
+    try {
+      await handleTelegramControlCallbackInternal(args);
+    } catch (error) {
+      console.error('[telegram-control] callback failed:', error);
+      const lang = languageFor(args.link);
+      await args.bot?.answerCallbackQuery(args.query?.id, { text: t(lang, 'error.generic') }).catch(() => {});
+      await send(args.bot, chatId, t(lang, 'error.generic')).catch(() => {});
+    }
+  });
+}