@desplega.ai/agent-swarm 1.173.0 → 2.1.0

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

@@ -0,0 +1,172 @@
+import {
+  getPendingChatRelayTasks,
+  giveUpStaleChatRelays,
+  markChatRelayAttempted,
+  markChatRelayDelivered,
+  markChatRelayGivenUp,
+  recordChatRelayError,
+} from "@/be/db";
+import { chatThreadOfContextKey } from "@/tasks/context-key";
+import type { AgentTask } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { workflowEventBus } from "@/workflows/event-bus";
+import { errorMessage } from "./logger";
+import { postChatMessage } from "./outbound";
+import { getChatInstance, getChatSdkHealth } from "./runtime";
+import { sweepExpired } from "./state";
+import { stopTypingKeepalive } from "./typing";
+
+/**
+ * Stop retrying a relay row this long after its obligation was created. Time,
+ * not attempts: with exponential backoff a short platform outage would
+ * otherwise burn a fixed attempt budget in minutes.
+ */
+export const RELAY_GIVE_UP_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Run `sweepExpired` on every Nth tick, including event-triggered ticks (so
+ * about once a minute when only the 3 s interval ticks).
+ */
+const SWEEP_EVERY_N_TICKS = 20;
+
+/** Coalesce bursts of terminal-task events into one early tick. */
+const EARLY_TICK_DEBOUNCE_MS = 250;
+
+/** The text posted for a terminal task. Failed and cancelled tasks get a status line first. */
+export function formatChatRelayText(task: AgentTask): string {
+  const body = (task.output || task.failureReason || "").trim();
+  if (task.status === "failed") return body ? `**Task failed.**\n\n${body}` : "**Task failed.**";
+  if (task.status === "cancelled") {
+    return body ? `**Task cancelled.**\n\n${body}` : "**Task cancelled.**";
+  }
+  return body || "Task completed.";
+}
+
+/**
+ * Deliver every pending, out-of-backoff chat relay row for a running adapter.
+ * Exported with an injectable clock so retry and give-up behavior is testable
+ * without waiting.
+ *
+ * Delivery is at-least-once: a chunk failure re-posts the earlier chunks on
+ * retry, and a crash between the send and `markChatRelayDelivered` re-sends the
+ * message.
+ *
+ * Once `signal` aborts, no further row is claimed. A send already in flight is
+ * not cancelled (`postChatMessage` takes no signal); its row keeps the claim
+ * and retries after the normal backoff.
+ */
+export async function processPendingChatRelays(
+  now: number = Date.now(),
+  signal?: AbortSignal,
+): Promise<void> {
+  // Rows older than the give-up age are retired first, so rows of a stopped
+  // adapter do not stay pending forever.
+  const retired = await giveUpStaleChatRelays(now, RELAY_GIVE_UP_AFTER_MS);
+  if (retired > 0) console.warn(`[chat-sdk] Gave up relaying ${retired} stale task(s)`);
+
+  const running = Object.entries(getChatSdkHealth())
+    .filter(([, adapterHealth]) => adapterHealth?.status === "ok")
+    .map(([name]) => name);
+
+  for (const pending of await getPendingChatRelayTasks(now, 200, running)) {
+    if (signal?.aborted) return;
+    const { task } = pending;
+    const target = chatThreadOfContextKey(task.contextKey);
+    // `created_at` is ISO text with a `Z` suffix (migration 217 default).
+    const createdAtMs = Date.parse(pending.createdAt);
+
+    if (Number.isFinite(createdAtMs) && now - createdAtMs >= RELAY_GIVE_UP_AFTER_MS) {
+      const reason = pending.lastError ?? "no successful delivery within 24 hours";
+      if (await markChatRelayGivenUp(task.id, reason, now)) {
+        console.warn(scrubSecrets(`[chat-sdk] Gave up relaying task ${task.id}: ${reason}`));
+      }
+      if (target) stopTypingKeepalive(target.threadId);
+      continue;
+    }
+    if (!target) {
+      // The trigger only enqueues chat-sdk keys; a key that no longer parses
+      // can never be delivered.
+      await markChatRelayGivenUp(task.id, "task has no chat-sdk contextKey", now);
+      continue;
+    }
+    // Stopping adapter: skip without counting an attempt.
+    if (!getChatInstance(target.adapter)) continue;
+
+    if (!(await markChatRelayAttempted(task.id, now))) continue;
+    try {
+      await postChatMessage({
+        adapter: target.adapter,
+        threadId: target.threadId,
+        text: formatChatRelayText(task),
+        taskId: task.id,
+      });
+      stopTypingKeepalive(target.threadId);
+      await markChatRelayDelivered(task.id, now);
+      console.log(`[chat-sdk] Relayed ${task.status} task ${task.id} to ${target.adapter}`);
+    } catch (error) {
+      const message = errorMessage(error);
+      await recordChatRelayError(task.id, message, now);
+      console.error(`[chat-sdk] Relay of task ${task.id} failed: ${message}`);
+    }
+  }
+}
+
+let interval: ReturnType<typeof setInterval> | undefined;
+let earlyTick: ReturnType<typeof setTimeout> | undefined;
+let processing: Promise<void> | undefined;
+let stopController: AbortController | undefined;
+let tickCount = 0;
+
+async function tick(): Promise<void> {
+  if (processing) return;
+  tickCount += 1;
+  const now = Date.now();
+  processing = (async () => {
+    try {
+      await processPendingChatRelays(now, stopController?.signal);
+      if (tickCount % SWEEP_EVERY_N_TICKS === 0) await sweepExpired(now);
+    } catch (error) {
+      console.error(`[chat-sdk] Relay tick failed: ${errorMessage(error)}`);
+    }
+  })();
+  try {
+    await processing;
+  } finally {
+    processing = undefined;
+  }
+}
+
+function scheduleEarlyTick(): void {
+  if (!interval || earlyTick) return;
+  earlyTick = setTimeout(() => {
+    earlyTick = undefined;
+    void tick();
+  }, EARLY_TICK_DEBOUNCE_MS);
+}
+
+const TERMINAL_EVENTS = ["task.completed", "task.failed", "task.cancelled"] as const;
+
+/** Start the relay watcher. Idempotent. A terminal task event triggers an early tick. */
+export function startChatRelayWatcher(intervalMs = 3000): void {
+  if (interval) return;
+  tickCount = 0;
+  stopController = new AbortController();
+  interval = setInterval(() => void tick(), intervalMs);
+  for (const event of TERMINAL_EVENTS) workflowEventBus.on(event, scheduleEarlyTick);
+  void tick();
+}
+
+/**
+ * Stop the watcher: no new tick, no new claim. The returned promise settles
+ * when an in-flight tick finishes, which an unanswered platform call can delay
+ * without bound, so shutdown waits for it under its own deadline.
+ */
+export async function stopChatRelayWatcher(): Promise<void> {
+  stopController?.abort();
+  if (interval) clearInterval(interval);
+  interval = undefined;
+  if (earlyTick) clearTimeout(earlyTick);
+  earlyTick = undefined;
+  for (const event of TERMINAL_EVENTS) workflowEventBus.off(event, scheduleEarlyTick);
+  if (processing) await processing;
+}

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

@@ -0,0 +1,169 @@
+import {
+  deleteKv,
+  getAgentById,
+  getAgentWorkingOnContextKey,
+  getAllAgents,
+  getKv,
+  getLeadAgent,
+  upsertKv,
+} from "@/be/db";
+import { isAgentReachable } from "@/be/runtime-pools/reachability";
+import { chatSdkContextKey } from "@/tasks/context-key";
+import type { Agent, RoutingReason } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+
+/** KV namespace of the channel-to-agent/workflow mapping, written by `register-chat-channel`. */
+export const CHAT_CHANNELS_NAMESPACE = "integrations:chat:channels";
+
+export interface ChatChannelMapping {
+  agentId?: string;
+  workflowId?: string;
+  name?: string;
+  createdAt?: string;
+}
+
+export interface ChatAgentMatch {
+  /** Null when no lead exists: the task is created unassigned and queued. */
+  agent: Agent | null;
+  reason: RoutingReason;
+  matchedText: string;
+}
+
+export type ChatRouteTarget =
+  | { kind: "agents"; matches: ChatAgentMatch[] }
+  | { kind: "workflow"; workflowId: string };
+
+export interface ChatRouteContext {
+  adapter: string;
+  channelId: string;
+  threadId: string;
+  botMentioned: boolean;
+  isDirectMessage: boolean;
+}
+
+/**
+ * KV key of a channel mapping. SDK channel ids already carry the adapter
+ * prefix (`telegram:555001`, `slack:C123`); the prefix is added only when an
+ * adapter returns a bare id, so the key is always `<adapter>:<platform id>`.
+ */
+export function chatChannelKey(adapter: string, channelId: string): string {
+  return channelId.startsWith(`${adapter}:`) ? channelId : `${adapter}:${channelId}`;
+}
+
+export async function getChatChannelMapping(
+  adapter: string,
+  channelId: string,
+): Promise<ChatChannelMapping | null> {
+  const row = await getKv(CHAT_CHANNELS_NAMESPACE, chatChannelKey(adapter, channelId));
+  if (!row || typeof row.value !== "object" || row.value === null) return null;
+  return row.value as ChatChannelMapping;
+}
+
+/** Store a channel mapping under `chatChannelKey(adapter, channelId)`. Returns the key. */
+export async function putChatChannelMapping(
+  adapter: string,
+  channelId: string,
+  mapping: ChatChannelMapping,
+): Promise<string> {
+  const key = chatChannelKey(adapter, channelId);
+  await upsertKv({
+    namespace: CHAT_CHANNELS_NAMESPACE,
+    key,
+    value: mapping,
+    valueType: "json",
+    expiresAt: null,
+  });
+  return key;
+}
+
+export async function deleteChatChannelMapping(
+  adapter: string,
+  channelId: string,
+): Promise<boolean> {
+  return deleteKv(CHAT_CHANNELS_NAMESPACE, chatChannelKey(adapter, channelId));
+}
+
+/** Remove `swarm#<uuid>` and `swarm#all` routing tokens from task text. */
+export function stripRoutingTokens(text: string): string {
+  return text
+    .replace(/swarm#[a-f0-9-]{36}/gi, "")
+    .replace(/swarm#all/gi, "")
+    .trim();
+}
+
+async function leadMatch(reachable: Agent[], matchedText: string): Promise<ChatAgentMatch> {
+  const lead = reachable.find((agent) => agent.isLead) ?? (await getLeadAgent());
+  return { agent: lead, reason: "skill", matchedText };
+}
+
+/**
+ * Port of `src/slack/router.ts` for Chat SDK threads. Order: `swarm#<uuid>`,
+ * `swarm#all`, KV channel mapping (agent, or workflow for a mention or DM), the
+ * thread owner (lead when the owner is offline), the lead for a mention or DM.
+ * Returns null when the message is not addressed to the swarm.
+ */
+export async function routeChatMessage(
+  text: string,
+  ctx: ChatRouteContext,
+): Promise<ChatRouteTarget | null> {
+  const allAgents = await getAllAgents();
+  const reachableFlags = await Promise.all(allAgents.map((agent) => isAgentReachable(agent)));
+  const reachable = allAgents.filter((_, index) => reachableFlags[index]);
+
+  const matches: ChatAgentMatch[] = [];
+  for (const match of text.matchAll(/swarm#([a-f0-9-]{36})/gi)) {
+    const agentId = match[1];
+    if (!agentId || matches.some((m) => m.agent?.id === agentId)) continue;
+    const agent = await getAgentById(agentId);
+    if (agent && (await isAgentReachable(agent))) {
+      matches.push({ agent, reason: "human_pinned", matchedText: match[0] });
+    }
+  }
+  if (/swarm#all/i.test(text)) {
+    for (const agent of reachable) {
+      if (agent.isLead || matches.some((m) => m.agent?.id === agent.id)) continue;
+      matches.push({ agent, reason: "human_pinned", matchedText: "swarm#all" });
+    }
+  }
+  if (matches.length > 0) return { kind: "agents", matches };
+
+  const mapping = await getChatChannelMapping(ctx.adapter, ctx.channelId);
+  // A workflow run has no continuity: an unaddressed reply in the subscribed
+  // thread must not start another run. It still reaches a thread owner below.
+  if (mapping?.workflowId && (ctx.botMentioned || ctx.isDirectMessage)) {
+    return { kind: "workflow", workflowId: mapping.workflowId };
+  }
+  if (mapping?.agentId) {
+    const agent = await getAgentById(mapping.agentId);
+    if (agent) {
+      return {
+        kind: "agents",
+        matches: [{ agent, reason: "human_pinned", matchedText: "channel mapping" }],
+      };
+    }
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] Channel mapping for ${ctx.channelId} names unknown agent ${mapping.agentId}; using the default route`,
+      ),
+    );
+  }
+
+  const owner = await getAgentWorkingOnContextKey(chatSdkContextKey(ctx.threadId), "chat");
+  if (owner && (await isAgentReachable(owner))) {
+    return {
+      kind: "agents",
+      matches: [{ agent: owner, reason: "continuity", matchedText: "thread follow-up" }],
+    };
+  }
+  if (owner) {
+    return {
+      kind: "agents",
+      matches: [await leadMatch(reachable, "thread follow-up (lead fallback)")],
+    };
+  }
+
+  if (ctx.botMentioned || ctx.isDirectMessage) {
+    return { kind: "agents", matches: [await leadMatch(reachable, "@bot")] };
+  }
+  return null;
+}

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

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import type { Chat } from "chat";
+import { isEnvFlagEnabled } from "@/utils/env-flag";
+import { registerVolatileSecret, scrubSecrets } from "@/utils/secret-scrubber";
+import { loadAdapter, watchSocketConnection } from "./adapters";
+import { drainBackground } from "./background";
+import { registerTelegramCommands } from "./commands";
+import {
+  assertNoSlackClash,
+  CHAT_SDK_ADAPTER_NAMES,
+  type ChatSdkAdapterName,
+  type ChatSdkConfig,
+  getChatSdkConfig,
+  type ResolvedAdapterConfig,
+} from "./config";
+import {
+  type DiscordGatewayHealth,
+  getDiscordGatewayHealth,
+  isDiscordGatewayListener,
+  resetDiscordGatewayHealth,
+  startDiscordGateway,
+  stopDiscordGateway,
+} from "./discord-gateway";
+import { registerChatHandlers } from "./handlers";
+import { createScrubbingLogger, errorMessage } from "./logger";
+import { startChatRelayWatcher, stopChatRelayWatcher } from "./relay";
+import { SqliteChatState } from "./state";
+import { getChatSdkTestHooks } from "./test-hooks";
+import { flushAllChatBuffers } from "./thread-buffer";
+import { stopAllTypingKeepalives } from "./typing";
+
+export interface ChatAdapterHealth {
+  status: "ok" | "error";
+  error?: string;
+  /** Last warn/error line the adapter logged, scrubbed. */
+  lastWarning?: string;
+  since: string;
+  /** Discord only: the supervised Gateway listener loop. */
+  gateway?: DiscordGatewayHealth;
+}
+
+/**
+ * One `Chat` per adapter. `Chat.initialize()` runs every adapter under one
+ * `Promise.all` and caches a failure forever, so a shared instance would let one
+ * broken adapter take every other adapter down. Health lives here, outside
+ * `Chat`, for the same reason.
+ */
+const instances = new Map<ChatSdkAdapterName, Chat>();
+const health = new Map<ChatSdkAdapterName, ChatAdapterHealth>();
+let stopping = false;
+/** Fingerprint of the config the last `startChatSdk` applied. */
+let appliedFingerprint: string | undefined;
+
+/** True while shutdown drains; the webhook path refuses new work. */
+export function isChatSdkStopping(): boolean {
+  return stopping;
+}
+
+const DEFAULT_CHAT_USER_NAME = "swarm";
+
+/** Total wait for every step of `stopChatSdk`, inside the 15 s SIGTERM budget. */
+const SHUTDOWN_BUDGET_MS = 10_000;
+/** A config reload waits this long for the adapters to come back before it answers. */
+const RELOAD_START_BUDGET_MS = 15_000;
+
+/** Fields whose string value is a credential, registered with the scrubber. */
+const SECRET_FIELDS = ["botToken", "secretToken", "signingSecret", "appToken", "appPassword"];
+
+function setHealth(
+  name: ChatSdkAdapterName,
+  status: "ok" | "error",
+  error: string | undefined,
+  lastWarning: string | undefined,
+): void {
+  health.set(name, { status, error, lastWarning, since: new Date().toISOString() });
+}
+
+/**
+ * Raw values in `CHAT_SDK_ADAPTERS` (env-only deployments) are not named by a
+ * sensitive env key, so the scrubber would not know them. `$config`-resolved
+ * secret rows are already registered by `loadGlobalConfigsIntoEnv`.
+ */
+async function registerAdapterSecrets(
+  name: ChatSdkAdapterName,
+  config: ResolvedAdapterConfig,
+): Promise<void> {
+  for (const field of SECRET_FIELDS) {
+    const raw = config[field];
+    const value = typeof raw === "function" ? await (raw as () => Promise<string>)() : raw;
+    if (typeof value === "string") {
+      registerVolatileSecret(value, `chat-sdk:${name}:${field}`);
+    }
+  }
+}
+
+async function startAdapter(
+  name: ChatSdkAdapterName,
+  config: ResolvedAdapterConfig,
+  state: SqliteChatState,
+  ChatClass: typeof Chat,
+): Promise<void> {
+  let lastWarning: string | undefined;
+  // No level prefix on the stored line: the message already says what failed,
+  // and the status payload carries the tone separately.
+  const logger = createScrubbingLogger(name, (_level, message) => {
+    lastWarning = message;
+    const current = health.get(name);
+    if (current) health.set(name, { ...current, lastWarning });
+  });
+  try {
+    await registerAdapterSecrets(name, config);
+    const adapter = await loadAdapter(name, config, logger);
+    const chat = new ChatClass({
+      adapters: { [name]: adapter },
+      state,
+      // Chat requires a userName. The adapter only gets one when the operator
+      // set it, so Telegram can still take the real bot name from getMe.
+      userName: typeof config.userName === "string" ? config.userName : DEFAULT_CHAT_USER_NAME,
+      logger,
+      // The swarm buffers bursts itself (Phase 2). The SDK "queue" strategy
+      // would keep only the latest queued message and skip the rest.
+      concurrency: "concurrent",
+    });
+    registerChatHandlers(chat);
+    instances.set(name, chat);
+    await chat.initialize();
+    // Shutdown began while this adapter initialized: do not mark it ready or
+    // start the Gateway after `stopChatSdk` already stopped it.
+    if (stopping) {
+      console.log(`[chat-sdk] ${name} initialized during shutdown, not started`);
+      return;
+    }
+    watchSocketConnection(adapter, logger);
+    if (name === "telegram") {
+      // The `/` menu in Telegram clients. The commands work without it.
+      try {
+        await registerTelegramCommands(config);
+      } catch (error) {
+        logger.warn(`Could not register the Telegram commands: ${errorMessage(error)}`);
+      }
+    }
+    setHealth(name, "ok", undefined, lastWarning);
+    console.log(`[chat-sdk] ${name} ready`);
+    // Discord messages arrive only over the Gateway, never the webhook.
+    if (
+      name === "discord" &&
+      isDiscordGatewayListener(adapter) &&
+      !getChatSdkTestHooks().disableDiscordGateway
+    ) {
+      startDiscordGateway(adapter);
+    }
+  } catch (error) {
+    setHealth(name, "error", errorMessage(error), lastWarning);
+    console.error(`[chat-sdk] ${name} failed to start: ${errorMessage(error)}`);
+  }
+}
+
+/**
+ * Boot the Chat SDK channel. Never throws for config or adapter problems: they
+ * are logged and recorded in health, and the API keeps booting.
+ */
+export async function startChatSdk(): Promise<void> {
+  stopping = false;
+  const config = await getChatSdkConfig();
+  appliedFingerprint = await configFingerprint(config);
+  if (!config.enabled) {
+    console.log("[chat-sdk] Disabled (CHAT_SDK_ENABLED is not true)");
+    return;
+  }
+  if (config.error) {
+    console.error(`[chat-sdk] Not started: ${scrubSecrets(config.error)}`);
+    return;
+  }
+  try {
+    assertNoSlackClash(config);
+  } catch (error) {
+    console.error(`[chat-sdk] Not started: ${errorMessage(error)}`);
+    return;
+  }
+  for (const [name, reason] of Object.entries(config.incomplete ?? {})) {
+    console.warn(`[chat-sdk] ${name} not started, incomplete: ${scrubSecrets(reason)}`);
+  }
+  const { Chat: ChatClass } = await import("chat");
+  const state = new SqliteChatState();
+  // In parallel: one slow adapter (Slack's WebClient retries auth.test for
+  // up to ~30 min on errors) must not delay the others.
+  // Before the adapters: rows for an adapter still initializing are skipped
+  // without counting an attempt, and pending rows from before a restart drain
+  // as soon as their adapter is up.
+  startChatRelayWatcher();
+  await Promise.all(
+    CHAT_SDK_ADAPTER_NAMES.map(async (name) => {
+      const adapterConfig = config.adapters[name];
+      if (adapterConfig) await startAdapter(name, adapterConfig, state, ChatClass);
+    }),
+  );
+}
+
+/** Only adapters whose `initialize()` succeeded serve webhooks. */
+export function getChatInstance(name: string): Chat | undefined {
+  const adapterName = name as ChatSdkAdapterName;
+  return health.get(adapterName)?.status === "ok" ? instances.get(adapterName) : undefined;
+}
+
+/** True when the adapter is configured (started, even if it failed). */
+export function isChatAdapterConfigured(name: string): boolean {
+  return health.has(name as ChatSdkAdapterName);
+}
+
+export function getChatSdkHealth(): Partial<Record<ChatSdkAdapterName, ChatAdapterHealth>> {
+  const out: Partial<Record<ChatSdkAdapterName, ChatAdapterHealth>> = Object.fromEntries(health);
+  const gateway = getDiscordGatewayHealth();
+  if (out.discord && gateway) out.discord = { ...out.discord, gateway };
+  return out;
+}
+
+/**
+ * Wait for `work`, at most `ms`. Never rejects: a rejection is logged, and a
+ * timeout logs the abandoned step. Returns true when `work` settled in time.
+ */
+async function withTimeout(work: Promise<unknown>, ms: number, step: string): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  const settled = work.then(
+    () => true as const,
+    (error: unknown) => {
+      console.error(`[chat-sdk] ${step} failed: ${errorMessage(error)}`);
+      return true as const;
+    },
+  );
+  try {
+    const done = await Promise.race([settled, timeout]);
+    if (!done) console.warn(`[chat-sdk] Shutdown budget spent, abandoned: ${step}`);
+    return done;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Stop the channel inside one deadline (`budgetMs`, injectable for tests). Every
+ * wait below uses the time that is left, so a stuck platform call cannot hold
+ * the API shutdown.
+ */
+export async function stopChatSdk(budgetMs: number = SHUTDOWN_BUDGET_MS): Promise<void> {
+  // Ingress first: webhooks answer 503 and refuse new work from here.
+  stopping = true;
+  stopAllTypingKeepalives();
+  const deadline = Date.now() + budgetMs;
+  const remaining = (): number => Math.max(0, deadline - Date.now());
+  // No new relay tick or claim from here. The wait for an in-flight send comes
+  // after the inbound flush, so a stuck send cannot use the flush's budget.
+  const relayStopped = stopChatRelayWatcher();
+  // Discord has no `disconnect()`, so `chat.shutdown()` would leave the
+  // Gateway open. Abort it before the drain: the open window is tracked
+  // background work, so the drain bounds the wait for it to close.
+  stopDiscordGateway();
+  // Let in-flight handlers finish buffering, then turn waiting threads into
+  // tasks while adapters and the DB are still up. Buffered messages exist only
+  // in memory: threads not flushed in time are lost (logged).
+  let drained = await drainBackground(remaining());
+  drained =
+    (await withTimeout(
+      flushAllChatBuffers(),
+      remaining(),
+      "inbound buffer flush (threads not yet turned into tasks are lost)",
+    )) && drained;
+  drained = (await drainBackground(remaining())) && drained;
+  // The relay posts through the adapters, so it must end before they shut
+  // down. An abandoned send keeps its claimed row: it retries after restart.
+  await withTimeout(
+    relayStopped,
+    remaining(),
+    "in-flight relay send (its obligation stays pending and retries after restart)",
+  );
+  await withTimeout(
+    Promise.all(
+      [...instances].map(async ([name, chat]) => {
+        try {
+          await chat.shutdown();
+        } catch (error) {
+          console.error(`[chat-sdk] ${name} shutdown failed: ${errorMessage(error)}`);
+        }
+      }),
+    ),
+    remaining(),
+    "adapter shutdown",
+  );
+  instances.clear();
+  health.clear();
+  resetDiscordGatewayHealth();
+  if (!drained) {
+    console.warn(
+      `[chat-sdk] Background handlers still running after the ${budgetMs / 1000}s shutdown budget`,
+    );
+  }
+}
+
+/**
+ * Hash of the resolved config plus `SLACK_DISABLE` (the Slack clash input).
+ * Resolver fields are functions, so their values are read first: a rotated
+ * `$config` secret changes the hash. The hashed JSON holds secrets: never log it.
+ */
+async function configFingerprint(config: ChatSdkConfig): Promise<string> {
+  const adapters: Record<string, Record<string, unknown>> = {};
+  for (const [name, adapterConfig] of Object.entries(config.adapters)) {
+    const fields: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(adapterConfig ?? {})) {
+      fields[key] = typeof value === "function" ? await (value as () => Promise<unknown>)() : value;
+    }
+    adapters[name] = fields;
+  }
+  const slackDisabled = isEnvFlagEnabled("SLACK_DISABLE", false);
+  // Incomplete adapters are not part of the running state, so editing one
+  // does not restart the adapters that run.
+  const { incomplete: _incomplete, disabled: _disabled, ...rest } = config;
+  return createHash("sha256")
+    .update(JSON.stringify({ ...rest, adapters, slackDisabled }))
+    .digest("hex");
+}
+
+/**
+ * Config reload hook: restart the adapters when the config differs from the
+ * one the last `startChatSdk` applied, so a dashboard save applies without an
+ * API restart. Compared against the applied config, not the pre-reload one:
+ * `$config` secrets resolve from the DB, which already holds the new row. An
+ * equal config leaves Telegram polling and the Discord Gateway alone. Never
+ * throws. Returns true when the restart left at least one adapter configured.
+ */
+export async function restartChatSdkIfConfigChanged(): Promise<boolean> {
+  try {
+    if ((await configFingerprint(await getChatSdkConfig())) === appliedFingerprint) return false;
+    console.log("[chat-sdk] Configuration changed, restarting adapters");
+    await stopChatSdk();
+    // Bounded: a Slack adapter can retry auth.test for a long time, and the
+    // reload must not hold every later config save behind it. The start
+    // continues in the background after the budget.
+    const started = await withTimeout(startChatSdk(), RELOAD_START_BUDGET_MS, "start after reload");
+    console.log(
+      started
+        ? `[chat-sdk] Restart done, adapters configured: ${health.size}`
+        : "[chat-sdk] Restart still in progress after the reload budget; check the card status",
+    );
+    return health.size > 0;
+  } catch (error) {
+    console.error(`[chat-sdk] Restart after configuration change failed: ${errorMessage(error)}`);
+    return false;
+  }
+}