@desplega.ai/agent-swarm 1.173.0 → 2.0.0

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 })),
+  });
+}

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

@@ -0,0 +1,198 @@
+import { ConfigRefError, resolveConfigRefs } from "@/be/config-refs";
+import { getSwarmConfigs } from "@/be/db";
+import { isReservedConfigKey } from "@/be/swarm-config-guard";
+import { isEnvFlagEnabled } from "@/utils/env-flag";
+import {
+  CHAT_SDK_ADAPTER_NAMES,
+  CHAT_SDK_ADAPTER_SCHEMAS,
+  type ChatSdkAdapterName,
+  type ChatSdkAdapters,
+  ChatSdkAdaptersDraftSchema,
+  firstIssueText,
+  isAdapterEntryEnabled,
+} from "./schema";
+
+export {
+  CHAT_SDK_ADAPTER_NAMES,
+  type ChatSdkAdapterName,
+  type ChatSdkAdapters,
+  ChatSdkAdaptersSchema,
+} from "./schema";
+
+class ChatSdkConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChatSdkConfigError";
+  }
+}
+
+/**
+ * Adapter config after `$config` resolution. Resolver-capable fields
+ * (`botToken`, `appId`, `applicationId`) are functions, every other field is
+ * the plain value. Passed to the adapter factory as-is.
+ */
+export type ResolvedAdapterConfig = Record<string, unknown>;
+
+export interface ChatSdkConfig {
+  enabled: boolean;
+  /** Adapters that are complete and resolved. Only these start. */
+  adapters: Partial<Record<ChatSdkAdapterName, ResolvedAdapterConfig>>;
+  /**
+   * Adapters present in `CHAT_SDK_ADAPTERS` that cannot start: a required
+   * field is missing (a partial dashboard save) or a `$config` reference does
+   * not resolve. The text names the field. The other adapters still start.
+   */
+  incomplete?: Partial<Record<ChatSdkAdapterName, string>>;
+  /** Adapters present with `enabled: false`: configured, kept, not started. */
+  disabled?: ChatSdkAdapterName[];
+  /** A problem with the whole value (bad JSON, unknown adapter, forbidden key): nothing starts. */
+  error?: string;
+}
+
+const RESOLVER_FIELDS = new Set(["botToken", "appId", "applicationId"]);
+
+/**
+ * Raw `CHAT_SDK_ENABLED` / `CHAT_SDK_ADAPTERS` from `process.env`. Boot runs
+ * `loadGlobalConfigsIntoEnv(true)` first, so stored swarm_config rows win over
+ * the deployment env (same mechanism as `SLACK_DISABLE`).
+ */
+function readChatSdkEnv(): { enabled: boolean; adaptersJson: string | undefined } {
+  const adaptersJson = process.env.CHAT_SDK_ADAPTERS?.trim();
+  return {
+    enabled: isEnvFlagEnabled("CHAT_SDK_ENABLED", false),
+    adaptersJson: adaptersJson ? adaptersJson : undefined,
+  };
+}
+
+/** True when `CHAT_SDK_ENABLED` resolves true. Drives the `chat-sdk` capability. */
+export function isChatSdkEnabled(): boolean {
+  return readChatSdkEnv().enabled;
+}
+
+/**
+ * Build the `$config` lookup over decrypted global swarm_config rows. Never
+ * reads `process.env`: leads can write ordinary global config, and an
+ * env-backed lookup would let `{"$config":"API_KEY"}` leave the host.
+ */
+async function buildSwarmConfigLookup(): Promise<(key: string) => string | undefined> {
+  const values = new Map<string, string>();
+  for (const row of await getSwarmConfigs({ scope: "global" })) {
+    if (typeof row.value === "string" && row.value.length > 0) values.set(row.key, row.value);
+  }
+  return (key) => {
+    if (isReservedConfigKey(key)) {
+      throw new ChatSdkConfigError(
+        `CHAT_SDK_ADAPTERS references reserved key '${key}', which is never resolvable`,
+      );
+    }
+    return values.get(key);
+  };
+}
+
+function toResolvedAdapterConfig(raw: Record<string, unknown>): ResolvedAdapterConfig {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    // The card's switch, not an adapter option.
+    if (key === "enabled") continue;
+    out[key] = RESOLVER_FIELDS.has(key) && typeof value === "string" ? async () => value : value;
+  }
+  return out;
+}
+
+/**
+ * Parse, validate and resolve the Chat SDK config. A problem with the whole
+ * value is returned in `error` with no adapters, so boot can log it and
+ * continue. A problem with one adapter (missing field, unresolvable `$config`)
+ * lands in `incomplete[name]` and the other adapters still resolve. Other
+ * errors (for example DB errors) propagate.
+ */
+export async function getChatSdkConfig(): Promise<ChatSdkConfig> {
+  const { enabled, adaptersJson } = readChatSdkEnv();
+  if (!enabled) return { enabled, adapters: {} };
+  if (!adaptersJson) {
+    return {
+      enabled,
+      adapters: {},
+      error: "CHAT_SDK_ENABLED is true but CHAT_SDK_ADAPTERS is empty",
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(adaptersJson);
+  } catch {
+    // Fixed text: the parser message can quote the input, which may hold an inline token.
+    return { enabled, adapters: {}, error: "CHAT_SDK_ADAPTERS is not valid JSON" };
+  }
+  // The draft shape guards the whole value: unknown adapters and forbidden
+  // keys stop everything. Required fields are checked per adapter below.
+  const draft = ChatSdkAdaptersDraftSchema.safeParse(parsed);
+  if (!draft.success) return { enabled, adapters: {}, error: firstIssueText(draft.error) };
+
+  const lookup = await buildSwarmConfigLookup();
+  const adapters: ChatSdkConfig["adapters"] = {};
+  const incomplete: NonNullable<ChatSdkConfig["incomplete"]> = {};
+  const disabled: ChatSdkAdapterName[] = [];
+  for (const name of CHAT_SDK_ADAPTER_NAMES) {
+    const entry = draft.data[name];
+    if (entry === undefined) continue;
+    if (!isAdapterEntryEnabled(entry)) {
+      disabled.push(name);
+      continue;
+    }
+    const validated = CHAT_SDK_ADAPTER_SCHEMAS[name].safeParse(entry);
+    if (!validated.success) {
+      incomplete[name] = firstIssueText(validated.error, `CHAT_SDK_ADAPTERS.${name}`, entry);
+      continue;
+    }
+    try {
+      const resolved = resolveConfigRefs<ChatSdkAdapters[typeof name]>(
+        validated.data as ChatSdkAdapters[typeof name],
+        lookup,
+      );
+      adapters[name] = toResolvedAdapterConfig(resolved as Record<string, unknown>);
+    } catch (error) {
+      if (!(error instanceof ChatSdkConfigError || error instanceof ConfigRefError)) throw error;
+      incomplete[name] = error.message;
+    }
+  }
+  return {
+    enabled,
+    adapters,
+    ...(Object.keys(incomplete).length > 0 ? { incomplete } : {}),
+    ...(disabled.length > 0 ? { disabled } : {}),
+  };
+}
+
+/**
+ * One Slack path per deployment: the Chat SDK Slack adapter requires the
+ * built-in Slack integration to be off. Evaluated on resolved config.
+ */
+export function assertNoSlackClash(config: ChatSdkConfig): void {
+  if (config.adapters.slack && !isEnvFlagEnabled("SLACK_DISABLE", false)) {
+    throw new ChatSdkConfigError(
+      "CHAT_SDK_ADAPTERS.slack conflicts with the built-in Slack integration; set SLACK_DISABLE=true to use the Chat SDK Slack adapter",
+    );
+  }
+}
+
+/**
+ * Env-only test/QA base URL overrides, keyed by adapter name
+ * (`CHAT_SDK_API_URL_OVERRIDES`, a RESERVED_KEYS entry, so never injected from
+ * a config row). Invalid JSON is ignored with an empty result.
+ */
+export function readApiUrlOverrides(): Partial<Record<ChatSdkAdapterName, string>> {
+  const raw = process.env.CHAT_SDK_API_URL_OVERRIDES?.trim();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: Partial<Record<ChatSdkAdapterName, string>> = {};
+    for (const name of CHAT_SDK_ADAPTER_NAMES) {
+      const value = (parsed as Record<string, unknown>)[name];
+      if (typeof value === "string" && value.length > 0) out[name] = value;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}

package/src/integrations/chat-sdk/discord-api.ts

@@ -0,0 +1,63 @@
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { resolveAdapterApiUrl } from "./adapters";
+import { errorMessage } from "./logger";
+
+const DISCORD_TIMEOUT_MS = 5_000;
+/** The status card polls every 5 s; one Discord call per minute is enough. */
+const GUILDS_CACHE_MS = 60_000;
+/** Bound on the server names the status carries. */
+const MAX_GUILD_NAMES = 10;
+
+export interface DiscordGuilds {
+  count: number;
+  /** Up to `MAX_GUILD_NAMES` server names, for the card. */
+  names: string[];
+}
+
+let cache: { token: string; at: number; guilds: DiscordGuilds | undefined } | undefined;
+
+/**
+ * The servers the bot was invited to (`GET /users/@me/guilds`). A connected
+ * Gateway with zero servers means the invite step was skipped, which the card
+ * can say outright. Undefined when Discord does not answer; the error is
+ * logged without the token.
+ */
+export async function fetchDiscordGuilds(
+  token: string,
+  now = Date.now(),
+): Promise<DiscordGuilds | undefined> {
+  if (cache && cache.token === token && now - cache.at < GUILDS_CACHE_MS) return cache.guilds;
+  let guilds: DiscordGuilds | undefined;
+  try {
+    const response = await fetch(`${resolveAdapterApiUrl("discord")}/users/@me/guilds`, {
+      headers: { authorization: `Bot ${token}` },
+      signal: AbortSignal.timeout(DISCORD_TIMEOUT_MS),
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const payload = (await response.json()) as unknown;
+    if (!Array.isArray(payload)) throw new Error("unexpected response shape");
+    const names = payload
+      .map((guild: unknown) =>
+        guild !== null &&
+        typeof guild === "object" &&
+        typeof (guild as { name?: unknown }).name === "string"
+          ? (guild as { name: string }).name
+          : undefined,
+      )
+      .filter((name): name is string => name !== undefined);
+    guilds = { count: payload.length, names: names.slice(0, MAX_GUILD_NAMES) };
+  } catch (error) {
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] discord: could not list the bot's servers: ${errorMessage(error).replaceAll(token, "[REDACTED]")}`,
+      ),
+    );
+  }
+  cache = { token, at: now, guilds };
+  return guilds;
+}
+
+/** Test seam. */
+export function resetDiscordGuildsCache(): void {
+  cache = undefined;
+}

package/src/integrations/chat-sdk/discord-gateway.ts

@@ -0,0 +1,185 @@
+import type { DiscordAdapter } from "@chat-adapter/discord";
+import type { Adapter } from "chat";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { trackBackground } from "./background";
+import { errorMessage } from "./logger";
+
+/**
+ * Discord sends channel messages and mentions only over the Gateway WebSocket.
+ * The adapter's `startGatewayListener` listens for one window and then
+ * destroys its client (it is built for serverless re-invocation), so a
+ * long-lived API process re-arms it in a loop. The adapter has no
+ * `disconnect()`, so `chat.shutdown()` does not stop the Gateway; aborting
+ * this loop is the only stop path.
+ *
+ * The Gateway does not replay `MESSAGE_CREATE`: messages sent during a re-arm
+ * gap or a backoff are lost. A long window keeps gaps rare. 6 h uses 4
+ * identifies per day of Discord's 1000.
+ */
+const DISCORD_GATEWAY_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** A window that ends sooner than this failed (bad token, network down). */
+const MIN_HEALTHY_WINDOW_MS = 10_000;
+const BACKOFF_MS = 30_000;
+/** Bound on the response body text logged when the listener refuses to start. */
+const MAX_LOGGED_BODY_CHARS = 200;
+
+export interface DiscordGatewayHealth {
+  state: "running" | "backoff" | "stopped";
+  since: string;
+  /** Re-arms after the first listener window. */
+  restarts: number;
+}
+
+/** The part of the Discord adapter the loop uses. */
+export type DiscordGatewayListener = Pick<DiscordAdapter, "startGatewayListener">;
+
+export function isDiscordGatewayListener(
+  adapter: Adapter,
+): adapter is Adapter & DiscordGatewayListener {
+  return "startGatewayListener" in adapter && typeof adapter.startGatewayListener === "function";
+}
+
+/** Test seams. Production uses the defaults. */
+export interface DiscordGatewayOptions {
+  windowMs?: number;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  now?: () => number;
+}
+
+/** Resolves after `ms`, or at once when `signal` aborts. */
+function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const done = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+let current: { controller: AbortController; loop: Promise<void>; now: () => number } | undefined;
+let health: DiscordGatewayHealth | undefined;
+
+function setState(state: DiscordGatewayHealth["state"], restarts: number, nowMs: number): void {
+  if (health?.state === state) {
+    health = { ...health, restarts };
+    return;
+  }
+  health = { state, since: new Date(nowMs).toISOString(), restarts };
+}
+
+async function runGatewayLoop(
+  adapter: DiscordGatewayListener,
+  signal: AbortSignal,
+  options: DiscordGatewayOptions,
+): Promise<void> {
+  const windowMs = options.windowMs ?? DISCORD_GATEWAY_WINDOW_MS;
+  const sleep = options.sleep ?? abortableSleep;
+  const now = options.now ?? Date.now;
+  let restarts = 0;
+  let first = true;
+  while (!signal.aborted) {
+    if (!first) restarts += 1;
+    first = false;
+    setState("running", restarts, now());
+    const started = now();
+    let inner: Promise<unknown> | undefined;
+    // One controller per window. The adapter adds an `abort` listener to the
+    // signal it gets and never removes it, so passing the outer signal would
+    // leak one listener (and the destroyed client) per re-arm.
+    const windowController = new AbortController();
+    const abortWindow = (): void => windowController.abort();
+    signal.addEventListener("abort", abortWindow, { once: true });
+    try {
+      const response = await adapter.startGatewayListener(
+        {
+          waitUntil: (task) => {
+            inner = task;
+            trackBackground(task);
+          },
+        },
+        windowMs,
+        windowController.signal,
+      );
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        console.error(
+          scrubSecrets(
+            `[chat-sdk] discord gateway listener refused to start: HTTP ${response.status}: ${body.slice(0, MAX_LOGGED_BODY_CHARS)}`,
+          ),
+        );
+      }
+      // The inner promise resolves when the window ends or on abort. It never
+      // rejects: login errors are logged by the adapter and end the window.
+      await inner;
+    } catch (error) {
+      console.error(
+        scrubSecrets(`[chat-sdk] discord gateway listener failed: ${errorMessage(error)}`),
+      );
+    } finally {
+      signal.removeEventListener("abort", abortWindow);
+    }
+    const elapsed = now() - started;
+    if (signal.aborted) break;
+    if (elapsed < MIN_HEALTHY_WINDOW_MS) {
+      setState("backoff", restarts, now());
+      console.warn(
+        scrubSecrets(
+          `[chat-sdk] discord gateway backoff: window ended after ${elapsed}ms, retrying in ${BACKOFF_MS / 1000}s`,
+        ),
+      );
+      await sleep(BACKOFF_MS, signal);
+    }
+  }
+}
+
+/**
+ * Start the supervised Gateway loop. Call only after `chat.initialize()`
+ * succeeded: the listener refuses to start before that.
+ */
+export function startDiscordGateway(
+  adapter: DiscordGatewayListener,
+  options: DiscordGatewayOptions = {},
+): void {
+  if (current) return;
+  const now = options.now ?? Date.now;
+  health = { state: "running", since: new Date(now()).toISOString(), restarts: 0 };
+  const controller = new AbortController();
+  const loop = runGatewayLoop(adapter, controller.signal, options).catch((error: unknown) => {
+    console.error(`[chat-sdk] discord gateway loop crashed: ${errorMessage(error)}`);
+  });
+  current = { controller, loop, now };
+}
+
+/**
+ * Abort the loop and return at once. The open window is tracked by
+ * `trackBackground`, so the shutdown drain bounds the wait for it to close.
+ * The `stopped` state and log line follow when the loop exits.
+ */
+export function stopDiscordGateway(): void {
+  if (!current) return;
+  const { controller, loop, now } = current;
+  current = undefined;
+  controller.abort();
+  void loop.then(() => {
+    // Skip when a new loop started, or when shutdown already reset health.
+    if (!current && health) setState("stopped", health.restarts, now());
+    console.log("[chat-sdk] discord gateway stopped");
+  });
+}
+
+export function getDiscordGatewayHealth(): DiscordGatewayHealth | undefined {
+  return health;
+}
+
+/** Forget the gateway record. Runtime shutdown clears adapter health the same way. */
+export function resetDiscordGatewayHealth(): void {
+  health = undefined;
+}

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

@@ -0,0 +1,28 @@
+import type { Chat, Message, Thread } from "chat";
+import { trackBackground } from "./background";
+import { registerChatCommands } from "./commands";
+import { type ChatInboundKind, handleChatInbound } from "./inbound";
+
+async function onHumanMessage(
+  thread: Thread,
+  message: Message,
+  kind: ChatInboundKind,
+): Promise<void> {
+  // The SDK drops the bot's own messages; other bots never become tasks.
+  if (message.author.isBot === true) return;
+  // Socket-mode events (Slack) reach the SDK without a request, so it has no
+  // `waitUntil` to hand this work to. Track it here so the shutdown drain
+  // waits for it before the DB closes. The tracker logs a rejection.
+  const work = handleChatInbound(thread, message, kind);
+  trackBackground(work);
+  await work.catch(() => undefined);
+}
+
+export function registerChatHandlers(chat: Chat): void {
+  chat.onNewMention((thread, message) => onHumanMessage(thread, message, "mention"));
+  chat.onDirectMessage((thread, message) => onHumanMessage(thread, message, "dm"));
+  chat.onSubscribedMessage((thread, message) => onHumanMessage(thread, message, "subscribed"));
+  // A `/command` message never reaches the handlers above: the adapters route
+  // it here. Without a handler Telegram would drop it silently.
+  registerChatCommands(chat);
+}