@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/src/http/webhooks.ts

@@ -66,6 +66,14 @@ import {
   verifyGitLabWebhook,
 } from "../gitlab";
 import { gitlabWorkflowActionName } from "../gitlab/workflow-action-name";
+import { trackBackground } from "../integrations/chat-sdk/background";
+import { isChatSdkEnabled } from "../integrations/chat-sdk/config";
+import {
+  getChatInstance,
+  isChatAdapterConfigured,
+  isChatSdkStopping,
+} from "../integrations/chat-sdk/runtime";
+import { isTrustedTeamsServiceUrl } from "../integrations/chat-sdk/teams-origin";
 import {
   type KapsoMessageActionResult,
   markKapsoMessageRead,
@@ -76,11 +84,14 @@ import { getKapsoConfig } from "../integrations/kapso/config";
 import type { KapsoWebhookPayload } from "../integrations/kapso/inbound";
 import { resolveKapsoRequestedByUserId, routeKapsoInbound } from "../integrations/kapso/inbound";
 import { TaskCreationBlockedError } from "../tasks/errors";
+import { getPublicMcpBaseUrl } from "../utils/constants";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { canonicalAzureDevOpsRepoUrl } from "../vcs/azure-devops";
 import { getExecutorRegistry } from "../workflows";
 import { workflowEventBus } from "../workflows/event-bus";
 import { handleWebhookTrigger, verifyHmacSignature, WebhookError } from "../workflows/triggers";
 import { route } from "./route-def";
+import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
 // ─── Route Definitions (documentation only — webhooks handle their own body parsing) ─
 
@@ -203,8 +214,75 @@ const kapsoWebhook = route({
   },
 });
 
+const chatSdkWebhook = route({
+  method: "post",
+  path: "/api/integrations/chat/{adapter}/webhook",
+  pattern: ["api", "integrations", "chat", null, "webhook"],
+  summary: "Handle Chat SDK platform webhooks (Telegram, Slack, Discord, Teams)",
+  tags: ["Webhooks"],
+  params: z.object({ adapter: z.string().describe("Chat SDK adapter name, e.g. telegram") }),
+  auth: { apiKey: false },
+  rbac: {
+    ungated:
+      "provider webhook: the Chat SDK adapter verifies the platform signature (Telegram secret token, Slack signing secret, Discord Ed25519, Teams JWT)",
+  },
+  responses: {
+    200: { description: "Adapter response", unstructured: "adapter response proxied as-is" },
+    401: { description: "Invalid platform signature or secret token" },
+    403: { description: "Teams activity whose serviceUrl is not a Bot Framework host" },
+    404: { description: "Chat SDK disabled or adapter not configured" },
+    413: { description: "Body exceeds 1 MiB" },
+    503: { description: "Adapter configured but failed to start" },
+  },
+});
+
+/**
+ * Upper bound for a Chat SDK webhook body. Platform payloads are a few KB and
+ * files travel by URL, so anything larger is not a platform delivery.
+ */
+const CHAT_SDK_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
+/** False when a Teams activity body carries a `serviceUrl` that is not a Bot Framework host. */
+function hasTrustedTeamsServiceUrl(body: Buffer): boolean {
+  let serviceUrl: unknown;
+  try {
+    serviceUrl = (JSON.parse(body.toString("utf-8")) as { serviceUrl?: unknown } | null)
+      ?.serviceUrl;
+  } catch {
+    // Not JSON: the adapter rejects it.
+    return true;
+  }
+  if (serviceUrl === undefined || serviceUrl === null || serviceUrl === "") return true;
+  return typeof serviceUrl === "string" && isTrustedTeamsServiceUrl(serviceUrl);
+}
+
+/**
+ * Rebuild a Fetch `Request` from the raw Node request. Headers come from
+ * `rawHeaders` pairs: building `Headers` from `IncomingMessage.headers`
+ * comma-joins repeated values, which breaks signature checks.
+ */
+function toFetchRequest(req: IncomingMessage, rawBody: Buffer, fallbackPath: string): Request {
+  const headers = new Headers();
+  if (Array.isArray(req.rawHeaders) && req.rawHeaders.length > 0) {
+    for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
+      headers.append(req.rawHeaders[i] as string, req.rawHeaders[i + 1] as string);
+    }
+  } else {
+    for (const [name, value] of Object.entries(req.headers)) {
+      for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
+        headers.append(name, item);
+      }
+    }
+  }
+  return new Request(`${getPublicMcpBaseUrl()}${req.url ?? fallbackPath}`, {
+    method: req.method ?? "POST",
+    headers,
+    body: rawBody.length > 0 ? new Uint8Array(rawBody) : undefined,
+  });
+}
+
 function logKapsoAckResult(action: string, result: KapsoMessageActionResult): void {
   if (result.ok) return;
   console.warn(
@@ -316,7 +394,8 @@ export async function handleWebhooks(
       return true;
     }
 
-    console.log(`[GitHub] Received ${eventType} event`);
+    const deliveryId = req.headers["x-github-delivery"] as string | undefined;
+    console.log(`[GitHub] Received ${eventType} event (delivery ${deliveryId ?? "unknown"})`);
 
     let result: WebhookDispatchResult = { created: false };
 
@@ -818,5 +897,84 @@ export async function handleWebhooks(
     return true;
   }
 
+  // Chat SDK webhook: the adapter verifies the platform signature over the raw
+  // body, so the request is proxied as-is and the adapter's response returned.
+  if (chatSdkWebhook.match(req.method, pathSegments)) {
+    const adapterName = pathSegments[3] ?? "";
+    if (!isChatSdkEnabled() || !isChatAdapterConfigured(adapterName)) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Chat SDK adapter not configured" }));
+      return true;
+    }
+    if (isChatSdkStopping()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Chat SDK is shutting down" }));
+      return true;
+    }
+    const chat = getChatInstance(adapterName);
+    const handler = chat?.webhooks[adapterName];
+    if (!handler) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Chat SDK adapter failed to start" }));
+      return true;
+    }
+
+    // The route is unauthenticated and the adapter verifies the signature over
+    // the buffered body, so the body is bounded before it is buffered. An
+    // oversized stream is answered at once and drained without buffering, the
+    // same way `parseBody` keeps the connection usable.
+    if (enforceContentLengthCap(req, res, CHAT_SDK_WEBHOOK_MAX_BODY_BYTES) === BODY_TOO_LARGE) {
+      return true;
+    }
+    const chunks: Buffer[] = [];
+    let receivedBytes = 0;
+    let tooLarge = false;
+    for await (const chunk of req) {
+      if (tooLarge) continue;
+      receivedBytes += (chunk as Buffer).byteLength;
+      if (receivedBytes > CHAT_SDK_WEBHOOK_MAX_BODY_BYTES) {
+        tooLarge = true;
+        chunks.length = 0;
+        jsonError(res, `Payload too large (max ${CHAT_SDK_WEBHOOK_MAX_BODY_BYTES} bytes)`, 413);
+        continue;
+      }
+      chunks.push(chunk as Buffer);
+    }
+    if (tooLarge) return true;
+    const rawBody = Buffer.concat(chunks);
+    // The Teams adapter replies, reads history and downloads files with the
+    // bot token at the activity's serviceUrl, and caches it for DMs. Refuse an
+    // untrusted one before the adapter sees the activity.
+    if (adapterName === "teams" && !hasTrustedTeamsServiceUrl(rawBody)) {
+      console.warn("[chat-sdk] teams webhook refused: serviceUrl is not a Bot Framework host");
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Untrusted Teams serviceUrl" }));
+      return true;
+    }
+    const request = toFetchRequest(req, rawBody, `/api/integrations/chat/${adapterName}/webhook`);
+
+    try {
+      const response = await handler(request, {
+        // Handler errors are logged by `trackBackground` in `handlers.ts`.
+        waitUntil: trackBackground,
+      });
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, name) => {
+        responseHeaders[name] = value;
+      });
+      const body = Buffer.from(await response.arrayBuffer());
+      res.writeHead(response.status, responseHeaders);
+      res.end(body);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[chat-sdk] ${adapterName} webhook failed: ${scrubSecrets(message)}`);
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+      }
+      res.end(JSON.stringify({ error: "Chat SDK webhook failed" }));
+    }
+    return true;
+  }
+
   return false;
 }

package/src/http/x.ts

@@ -255,6 +255,7 @@ export async function handleX(
     timeoutMs,
     egressSecrets: credentials.egressSecrets,
     failedBindings: credentials.failedBindings,
+    userConfig: credentials.userConfig,
     apiConnections: getScriptApiConnectionDescriptors({ agentId: endpoint.agentId }),
     mcpConnections: getScriptMcpConnectionDescriptors({ agentId: endpoint.agentId }),
   });

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