@desplega.ai/agent-swarm 1.172.0 → 2.0.0

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

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 {};
+  }
+}