@desplega.ai/agent-swarm 1.173.0 → 2.1.0

package/src/integrations/chat-sdk/adapters.ts

@@ -0,0 +1,129 @@
+import type { Adapter, Logger } from "chat";
+import { type ChatSdkAdapterName, type ResolvedAdapterConfig, readApiUrlOverrides } from "./config";
+import { withInfoFilter } from "./logger";
+import { getChatSdkTestHooks } from "./test-hooks";
+
+/**
+ * Platform API bases passed explicitly so the adapters never fall back to
+ * `TELEGRAM_API_BASE_URL` / `SLACK_API_URL` / `DISCORD_API_URL` /
+ * `TEAMS_API_URL` from `process.env`. Global swarm_config rows are injected
+ * into `process.env`, so an env fallback would let a config row redirect bot
+ * tokens to another host. Teams gets "" which blocks only `TEAMS_API_URL`.
+ * The other Teams SDK env fallbacks (`SERVICE_URL`, `TENANT_ID`, `CLIENT_ID`,
+ * `CLIENT_SECRET`, `MANAGED_IDENTITY_CLIENT_ID`, `CLOUD`) are closed by the
+ * injection denylist in `getInjectableGlobalConfigs` (`src/be/db.ts`).
+ * Deployment env can still set them on purpose.
+ */
+const DEFAULT_API_URLS: Record<ChatSdkAdapterName, string> = {
+  telegram: "https://api.telegram.org",
+  slack: "https://slack.com/api/",
+  discord: "https://discord.com/api/v10",
+  teams: "",
+};
+
+/**
+ * Discord adapter info lines dropped from the logs. They fire per event and
+ * carry guild message content (first 100 chars), or the public key and
+ * signature prefix of every interaction. Warn and error lines are kept.
+ */
+const DISCORD_NOISY_INFO_PREFIXES = [
+  "Discord Gateway message received",
+  "Discord webhook received",
+  "Discord signature verification",
+  "Discord interaction parsed",
+  "Discord PING received",
+];
+
+export function keepDiscordInfoLine(message: string): boolean {
+  return !DISCORD_NOISY_INFO_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+/**
+ * Platform API base for one adapter: the env-only `CHAT_SDK_API_URL_OVERRIDES`
+ * entry, else the platform default. The adapters and the Telegram
+ * register-webhook route use the same base.
+ */
+export function resolveAdapterApiUrl(name: ChatSdkAdapterName): string {
+  return readApiUrlOverrides()[name] ?? DEFAULT_API_URLS[name];
+}
+
+/**
+ * Construct one adapter. Each branch is a literal-path dynamic import so
+ * `bun build --compile` bundles it (a computed specifier is not bundled).
+ * `apiUrl` comes only from the env-only `CHAT_SDK_API_URL_OVERRIDES`.
+ */
+export async function loadAdapter(
+  name: ChatSdkAdapterName,
+  config: ResolvedAdapterConfig,
+  logger: Logger,
+): Promise<Adapter> {
+  const apiUrl = resolveAdapterApiUrl(name);
+  const base = { ...config, apiUrl, logger };
+  switch (name) {
+    case "telegram": {
+      const { createTelegramAdapter } = await import("@chat-adapter/telegram");
+      // Explicit `false` blocks the TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS env fallback.
+      return createTelegramAdapter({ ...base, allowUnverifiedWebhooks: false } as Parameters<
+        typeof createTelegramAdapter
+      >[0]);
+    }
+    case "slack": {
+      const { createSlackAdapter } = await import("@chat-adapter/slack");
+      // "" (not undefined) blocks each `?? process.env.SLACK_*` fallback, which
+      // would pick up the built-in Slack app's secrets. Socket forwarding and
+      // the installation encryption key are multi-workspace features we do not
+      // use; "" turns both off.
+      return createSlackAdapter({
+        ...base,
+        signingSecret: config.signingSecret ?? "",
+        appToken: config.appToken ?? "",
+        socketForwardingSecret: "",
+        encryptionKey: "",
+      } as Parameters<typeof createSlackAdapter>[0]);
+    }
+    case "discord": {
+      const { createDiscordAdapter } = await import("@chat-adapter/discord");
+      // `[]` (not undefined) blocks the DISCORD_RESPOND_TO_CHANNEL_IDS and
+      // DISCORD_MENTION_ROLE_IDS env fallbacks.
+      return createDiscordAdapter({
+        ...base,
+        logger: withInfoFilter(logger, keepDiscordInfoLine),
+        respondToChannelIds: config.respondToChannelIds ?? [],
+        mentionRoleIds: config.mentionRoleIds ?? [],
+      } as Parameters<typeof createDiscordAdapter>[0]);
+    }
+    case "teams": {
+      const { createTeamsAdapter } = await import("@chat-adapter/teams");
+      // `webhookVerifier` replaces the Bot Framework JWT check and `token` the
+      // bot token call. Only tests set them (test-hooks.ts); the operator
+      // schema rejects `webhookVerifier`, and `token` is a function.
+      const { teamsWebhookVerifier, teamsToken } = getChatSdkTestHooks();
+      return createTeamsAdapter({
+        ...base,
+        ...(teamsWebhookVerifier ? { webhookVerifier: teamsWebhookVerifier } : {}),
+        ...(teamsToken ? { token: teamsToken } : {}),
+      } as Parameters<typeof createTeamsAdapter>[0]);
+    }
+  }
+}
+
+type SocketClientLike = { on(event: string, listener: () => void): unknown };
+
+/**
+ * Slack socket mode reconnects on its own and logs through its own logger,
+ * not ours. Surface hard failures through the scrubbing logger so adapter
+ * health (`lastWarning`) shows them. A failed first connect rejects
+ * `initialize()` for auth errors. Network failures go through the WebClient
+ * retry policy and can take long before they surface here.
+ * `reconnecting` also fires on Slack's routine connection refresh, so it is
+ * logged at info only and never reaches health.
+ */
+export function watchSocketConnection(adapter: Adapter, logger: Logger): void {
+  const client = (adapter as { socketClient?: SocketClientLike }).socketClient;
+  if (!client) return;
+  client.on("reconnecting", () => logger.info("Slack socket mode reconnecting"));
+  client.on("unable_to_socket_mode_start", () =>
+    logger.warn("Slack socket mode unable to start, retrying"),
+  );
+  client.on("error", () => logger.warn("Slack socket mode error"));
+}

package/src/integrations/chat-sdk/attachments.ts

@@ -0,0 +1,232 @@
+/**
+ * Chat SDK attachments turned into task attachments. A copy of the Slack
+ * inbound-files flow (`src/slack/inbound-files.ts`), not an extraction: the
+ * Slack integration is left as is.
+ *
+ * Each attachment is fetched once per buffer flush through the adapter's own
+ * `fetchData()` (it carries the platform auth), spooled to a temp file, then
+ * stored through the active file provider and recorded as a `task_attachments`
+ * row. The task is created in `draft` while its uploads run, with its lease
+ * renewed, so no worker can claim it before its attachments exist. Every file
+ * also stays in the task text as a `[File: ...]` line. Only a fetch failure is
+ * flagged there; upload and record failures are logged.
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Attachment } from "chat";
+import { getTaskAttachments, promoteDraftTask, refreshDraftTaskLease } from "@/be/db";
+import { MAX_TASK_ATTACHMENT_BYTES, recordTaskAttachmentUpload } from "@/be/task-attachment-store";
+import { providerPath } from "@/fs/provider";
+import { getFileStorageProvider } from "@/fs/registry";
+import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import type { AgentTask, CreateTaskOptions } from "@/types";
+import { errorMessage } from "./logger";
+
+/** How often a draft's lease is renewed while its uploads run; the sweep waits 5 minutes. */
+const DRAFT_LEASE_REFRESH_MS = 60_000;
+/** A file a user sent the bot, like one uploaded from the dashboard composer. */
+const SHARED_FILE_INTENT = "user-upload";
+
+/**
+ * One attachment of a buffered chat message. `id` is `<messageId>-<n>` with
+ * every character outside `[A-Za-z0-9_.-]` replaced by `_` (Telegram message
+ * ids carry the chat id and a colon); it names the stored blob.
+ */
+export interface ChatFile {
+  id: string;
+  adapter: string;
+  messageId: string;
+  name: string;
+  mimeType?: string;
+  size?: number;
+  attachment: Attachment;
+}
+
+export type ChatFileFailure = { file: ChatFile; reason: string };
+
+export type FetchedChatFile = { file: ChatFile; path: string; sizeBytes: number; sha256: string };
+
+export type InboundChatFiles = {
+  files: ChatFile[];
+  fetched: FetchedChatFile[];
+  failed: ChatFileFailure[];
+  /** Deletes the downloaded copies; hold the batch with `await using`. */
+  [Symbol.asyncDispose](): Promise<void>;
+};
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+/** Describe the attachments of one message as `ChatFile`s. */
+export function toChatFiles(
+  adapter: string,
+  messageId: string,
+  attachments: Attachment[],
+): ChatFile[] {
+  return attachments.map((attachment, index) => ({
+    id: `${messageId}-${index + 1}`.replace(/[^\w.-]/g, "_"),
+    adapter,
+    messageId,
+    name: attachment.name ?? `${attachment.type}-${index + 1}`,
+    mimeType: attachment.mimeType,
+    size: attachment.size,
+    attachment,
+  }));
+}
+
+/**
+ * `[File: <name> (<mime>, <size>) id=<id>]` per file, followed by
+ * `(not attached: <reason>)` when the file never reached the task.
+ */
+export function buildChatAttachmentText(files: ChatFile[], failed: ChatFileFailure[] = []): string {
+  const reasons = new Map(failed.map((f) => [f.file.id, f.reason]));
+  return files
+    .map((f) => {
+      const size = typeof f.size === "number" ? formatFileSize(f.size) : "unknown size";
+      const line = `[File: ${f.name} (${f.mimeType ?? "unknown type"}, ${size}) id=${f.id}]`;
+      const reason = reasons.get(f.id);
+      return reason ? `${line} (not attached: ${reason})` : line;
+    })
+    .join("\n");
+}
+
+async function readAttachment(attachment: Attachment): Promise<Uint8Array> {
+  if (attachment.data instanceof Blob) return new Uint8Array(await attachment.data.arrayBuffer());
+  if (attachment.data) return new Uint8Array(attachment.data);
+  if (!attachment.fetchData) throw new Error("the adapter gave no way to download it");
+  const data = await attachment.fetchData();
+  return new Uint8Array(data);
+}
+
+/**
+ * Download every attachment, each to its own temp file. Never throws: a file
+ * that cannot be fetched lands in `failed` with a readable reason.
+ */
+export async function fetchChatFiles(files: ChatFile[]): Promise<InboundChatFiles> {
+  let dir: string | undefined;
+  const result: InboundChatFiles = {
+    files,
+    fetched: [],
+    failed: [],
+    async [Symbol.asyncDispose]() {
+      if (dir) await rm(dir, { recursive: true, force: true });
+    },
+  };
+  if (files.length === 0) return result;
+
+  const limit = `larger than the ${MAX_TASK_ATTACHMENT_BYTES / (1024 * 1024)} MB limit`;
+  dir = await mkdtemp(join(tmpdir(), "chat-files-"));
+  for (const [index, file] of files.entries()) {
+    if (typeof file.size === "number" && file.size > MAX_TASK_ATTACHMENT_BYTES) {
+      result.failed.push({ file, reason: limit });
+      continue;
+    }
+    try {
+      const bytes = await readAttachment(file.attachment);
+      if (bytes.byteLength > MAX_TASK_ATTACHMENT_BYTES) {
+        result.failed.push({ file, reason: limit });
+        continue;
+      }
+      const path = join(dir, String(index));
+      await Bun.write(path, bytes);
+      const sha256 = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+      file.size ??= bytes.byteLength;
+      result.fetched.push({ file, path, sizeBytes: bytes.byteLength, sha256 });
+    } catch (error) {
+      const reason = `download failed (${errorMessage(error)})`;
+      console.warn(`[chat-sdk] could not fetch file ${file.id}: ${reason}`);
+      result.failed.push({ file, reason });
+    }
+  }
+  return result;
+}
+
+/**
+ * Create a chat-sourced task and attach the fetched files. Without files this
+ * is `createTaskWithSiblingAwareness`. With files the task is created in
+ * `draft` and promoted once every upload has settled, success or not.
+ */
+export async function createChatTaskWithFiles(
+  description: string,
+  options: CreateTaskOptions,
+  inbound: InboundChatFiles,
+): Promise<{ task: AgentTask; unattached: ChatFileFailure[] }> {
+  if (inbound.fetched.length === 0) {
+    const task = await createTaskWithSiblingAwareness(description, options, { origin: "webhook" });
+    return { task, unattached: inbound.failed };
+  }
+
+  const task = await createTaskWithSiblingAwareness(
+    description,
+    { ...options, status: "draft" },
+    { origin: "webhook" },
+  );
+  const unattached = [...inbound.failed];
+  const lease = setInterval(() => {
+    void refreshDraftTaskLease(task.id).catch((error) =>
+      console.warn(
+        `[chat-sdk] could not renew the draft lease of task ${task.id}: ${errorMessage(error)}`,
+      ),
+    );
+  }, DRAFT_LEASE_REFRESH_MS);
+  try {
+    unattached.push(...(await attachChatFilesToTask(task.id, inbound.fetched)));
+  } finally {
+    clearInterval(lease);
+    await promoteDraftTask(task.id);
+  }
+  return { task, unattached };
+}
+
+/**
+ * Store fetched chat files as attachments of a task. A file whose bytes the
+ * task already holds is reused. Returns the files that could not be stored.
+ */
+export async function attachChatFilesToTask(
+  taskId: string,
+  fetched: FetchedChatFile[],
+): Promise<ChatFileFailure[]> {
+  const existing = await getTaskAttachments(taskId);
+  const bySha = new Set(existing.flatMap((a) => (a.sha256 ? [a.sha256] : [])));
+  const usedNames = new Set(existing.map((a) => a.name));
+  const provider = getFileStorageProvider();
+  const unattached: ChatFileFailure[] = [];
+
+  for (const { file, path, sizeBytes, sha256 } of fetched) {
+    if (bySha.has(sha256)) continue;
+    const name = usedNames.has(file.name) ? `${file.id}-${file.name}` : file.name;
+    usedNames.add(name);
+    const key = providerPath({ taskId, name: `chat-${file.id}-${file.name}` });
+    const scope = { taskId, name, key };
+    const contentType = file.mimeType ?? "application/octet-stream";
+    try {
+      const uploaded = await provider.upload(scope, Bun.file(path), {
+        contentType,
+        sizeBytes,
+        message: `Upload ${name} from ${file.adapter} for task ${taskId}`,
+      });
+      await recordTaskAttachmentUpload({
+        provider,
+        scope,
+        uploaded,
+        sizeBytes,
+        sha256,
+        contentType,
+        agentId: null,
+        intent: SHARED_FILE_INTENT,
+        description: `Shared on ${file.adapter} (message ${file.messageId})`,
+      });
+      bySha.add(sha256);
+    } catch (error) {
+      const reason = `could not be stored (${errorMessage(error)})`;
+      console.warn(`[chat-sdk] file ${file.id} for task ${taskId} ${reason}`);
+      unattached.push({ file, reason });
+    }
+  }
+  return unattached;
+}

package/src/integrations/chat-sdk/background.ts

@@ -0,0 +1,36 @@
+import { scrubSecrets } from "@/utils/secret-scrubber";
+
+/**
+ * In-process `waitUntil` for Chat SDK webhooks. The SDK hands handler work to
+ * `waitUntil` and answers the platform immediately; this tracker keeps that
+ * work visible so shutdown can drain it before the DB closes.
+ */
+const inFlight = new Set<Promise<unknown>>();
+
+/** The `waitUntil` implementation: track, and scrub-log any rejection. */
+export function trackBackground(task: Promise<unknown>): void {
+  const tracked = task.then(
+    () => undefined,
+    (error: unknown) => {
+      const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      console.error("[chat-sdk] Background handler failed:", scrubSecrets(message));
+    },
+  );
+  inFlight.add(tracked);
+  void tracked.finally(() => inFlight.delete(tracked));
+}
+
+/** Await in-flight work, bounded by `timeoutMs`. Returns true when fully drained. */
+export async function drainBackground(timeoutMs: number): Promise<boolean> {
+  if (inFlight.size === 0) return true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), timeoutMs);
+  });
+  const drained = Promise.all([...inFlight]).then(() => true as const);
+  try {
+    return await Promise.race([drained, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/integrations/chat-sdk/commands.ts

@@ -0,0 +1,194 @@
+import type { Chat, SlashCommandEvent } from "chat";
+import {
+  cancelTask,
+  getAgentById,
+  getLatestActiveTaskByContextKey,
+  getLatestTaskByContextKey,
+  updateAgentStatusFromCapacity,
+} from "@/be/db";
+import { chatSdkContextKey } from "@/tasks/context-key";
+import type { AgentTask } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { resolveAdapterApiUrl } from "./adapters";
+import { trackBackground } from "./background";
+import type { ResolvedAdapterConfig } from "./config";
+import { errorMessage } from "./logger";
+import { SqliteChatState } from "./state";
+import { callTelegramBotApi } from "./telegram-api";
+import { stopTypingKeepalive } from "./typing";
+
+/**
+ * Slash commands the swarm answers on every adapter that delivers them
+ * (Telegram, Discord, Slack). The platform learns the list in its own way:
+ * Telegram through `setMyCommands` at adapter start, Discord through a
+ * one-time application-command registration, Slack through the app manifest.
+ * Names follow the Telegram rules (lowercase, 1-32 chars) so one list fits all.
+ */
+export interface ChatCommandSpec {
+  command: string;
+  description: string;
+}
+
+export const CHAT_COMMANDS: readonly ChatCommandSpec[] = [
+  { command: "help", description: "List the commands" },
+  { command: "status", description: "Show the latest task of this chat" },
+  { command: "cancel", description: "Cancel the running task of this chat" },
+  { command: "reset", description: "Start over: the next message gets no earlier context" },
+];
+
+const RESET_KEY_PREFIX = "swarm:reset:";
+const RESET_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** Upper bound on the active tasks `/cancel` walks in one chat. */
+const CANCEL_LIMIT = 20;
+
+/**
+ * Record that the user reset the conversation. The next flush in this thread
+ * creates a task with no parent and no thread history older than this mark.
+ */
+export async function markChatThreadReset(threadId: string): Promise<Date> {
+  const at = new Date();
+  await new SqliteChatState().set(`${RESET_KEY_PREFIX}${threadId}`, at.toISOString(), RESET_TTL_MS);
+  return at;
+}
+
+/** The last `/reset` in this thread, or null. */
+export async function getChatThreadResetAt(threadId: string): Promise<Date | null> {
+  const raw = await new SqliteChatState().get<string>(`${RESET_KEY_PREFIX}${threadId}`);
+  if (typeof raw !== "string") return null;
+  const at = new Date(raw);
+  return Number.isNaN(at.getTime()) ? null : at;
+}
+
+function helpText(): string {
+  return ["Commands:", ...CHAT_COMMANDS.map((c) => `/${c.command}: ${c.description}`)].join("\n");
+}
+
+function shortId(task: AgentTask): string {
+  return task.id.slice(0, 8);
+}
+
+async function assigneeLabel(task: AgentTask): Promise<string> {
+  if (!task.agentId) return "waiting for an agent";
+  const agent = await getAgentById(task.agentId);
+  return agent ? `assigned to ${agent.name}` : "assigned to a removed agent";
+}
+
+async function statusText(contextKey: string): Promise<string> {
+  const latest = await getLatestTaskByContextKey(contextKey);
+  if (!latest) return "No task yet for this chat. Send a message to create one.";
+  const lines = [
+    `Latest task ${shortId(latest)}: ${latest.status}, ${await assigneeLabel(latest)}.`,
+  ];
+  if (latest.status === "pending" || latest.status === "in_progress") {
+    lines.push("Send /cancel to stop it.");
+  }
+  return lines.join("\n");
+}
+
+async function cancelActiveTasks(
+  contextKey: string,
+  threadId: string,
+  requestedBy: string,
+): Promise<string> {
+  const cancelled: AgentTask[] = [];
+  for (let i = 0; i < CANCEL_LIMIT; i++) {
+    const active = await getLatestActiveTaskByContextKey(contextKey, "chat");
+    if (!active) break;
+    const task = await cancelTask(active.id, `Cancelled from chat by ${requestedBy}`);
+    if (!task) break;
+    if (task.agentId) await updateAgentStatusFromCapacity(task.agentId);
+    cancelled.push(task);
+  }
+  stopTypingKeepalive(threadId);
+  if (cancelled.length === 0) return "No running task in this chat.";
+  const ids = cancelled.map(shortId).join(", ");
+  return cancelled.length === 1
+    ? `Cancelled task ${ids}.`
+    : `Cancelled ${cancelled.length} tasks: ${ids}.`;
+}
+
+/** The reply for one command. Exported for tests; the handler posts it. */
+export async function runChatCommand(
+  command: string,
+  threadId: string,
+  requestedBy: string,
+): Promise<string> {
+  const name = command.replace(/^\//, "").toLowerCase();
+  if (name === "help") return helpText();
+  if (!CHAT_COMMANDS.some((c) => c.command === name)) {
+    return `Unknown command /${name}.\n${helpText()}`;
+  }
+  let contextKey: string;
+  try {
+    contextKey = chatSdkContextKey(threadId);
+  } catch {
+    return "This command works only in a chat the swarm can address.";
+  }
+  switch (name) {
+    case "status":
+      return statusText(contextKey);
+    case "cancel":
+      return cancelActiveTasks(contextKey, threadId, requestedBy);
+    case "reset": {
+      await markChatThreadReset(threadId);
+      const lines = ["Context reset. Your next message starts a new conversation."];
+      // A running task is state, not context: it keeps going, and the next task
+      // is still created next to it. Only /cancel stops it.
+      if (await getLatestActiveTaskByContextKey(contextKey, "chat")) {
+        lines.push("A task is still running in this chat. Send /cancel to stop it.");
+      }
+      return lines.join("\n");
+    }
+    default:
+      return helpText();
+  }
+}
+
+async function onSlashCommand(event: SlashCommandEvent): Promise<void> {
+  const adapter = event.adapter.name;
+  // Telegram passes the thread id as the channel id. Slack and Discord pass
+  // the channel, so a command there addresses the channel-level thread.
+  const threadId = event.channel.id;
+  const requestedBy = event.user.userName || event.user.fullName || event.user.userId;
+  console.log(`[chat-sdk] ${adapter} ${threadId}: command ${event.command} from ${requestedBy}`);
+  let reply: string;
+  try {
+    reply = await runChatCommand(event.command, threadId, requestedBy);
+  } catch (error) {
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] ${threadId}: command ${event.command} failed: ${errorMessage(error)}`,
+      ),
+    );
+    reply = "The command failed. Check the API log.";
+  }
+  try {
+    await event.channel.post(scrubSecrets(reply));
+  } catch (error) {
+    console.warn(
+      `[chat-sdk] ${threadId}: could not answer ${event.command}: ${errorMessage(error)}`,
+    );
+  }
+}
+
+/** Catch-all handler: known commands act, unknown ones get the list. */
+export function registerChatCommands(chat: Chat): void {
+  chat.onSlashCommand((event) => {
+    const work = onSlashCommand(event);
+    trackBackground(work);
+    return work.catch(() => undefined);
+  });
+}
+
+/**
+ * Publish the command list to Telegram so the client shows the `/` menu.
+ * Called after the adapter initialized; a failure is logged, never fatal.
+ */
+export async function registerTelegramCommands(config: ResolvedAdapterConfig): Promise<void> {
+  const raw = config.botToken;
+  const token = typeof raw === "function" ? await (raw as () => Promise<string>)() : raw;
+  if (typeof token !== "string" || token.length === 0) return;
+  await callTelegramBotApi(resolveAdapterApiUrl("telegram"), token, "setMyCommands", {
+    commands: CHAT_COMMANDS.map((c) => ({ command: c.command, description: c.description })),
+  });
+}