@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/tests/chat-sdk-discord-webhook.test.ts

@@ -0,0 +1,126 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, initDb } from "../be/db";
+import {
+  type DiscordGatewayListener,
+  getDiscordGatewayHealth,
+  startDiscordGateway,
+} from "../integrations/chat-sdk/discord-gateway";
+import { stopChatRelayWatcher } from "../integrations/chat-sdk/relay";
+import { getChatSdkHealth, startChatSdk, stopChatSdk } from "../integrations/chat-sdk/runtime";
+import { setChatSdkTestHooks } from "../integrations/chat-sdk/test-hooks";
+import { postChatWebhook, snapshotChatSdkEnv } from "./chat-sdk-harness";
+import { getFreePort } from "./test-net";
+
+/*
+ * Network: Discord `initialize()` only resolves the application id (no API
+ * call), and a PING is answered from the signature check alone. The Gateway
+ * loop is off through the test hook: it logs in through `discord.js`, which
+ * ignores `apiUrl` and would reach the real Discord API. `apiUrl` points at a
+ * port nothing listens on, so an unexpected REST call fails here.
+ */
+const TEST_DB_PATH = "./test-chat-sdk-discord-webhook.sqlite";
+const restoreEnv = snapshotChatSdkEnv();
+let privateKey: CryptoKey;
+
+function toHex(bytes: ArrayBuffer): string {
+  return Buffer.from(bytes).toString("hex");
+}
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+}
+
+/** Discord signs `timestamp + body` with the application's Ed25519 key. */
+async function signedHeaders(body: string): Promise<Record<string, string>> {
+  const timestamp = String(Math.floor(Date.now() / 1000));
+  const signature = await crypto.subtle.sign(
+    "Ed25519",
+    privateKey,
+    new TextEncoder().encode(timestamp + body),
+  );
+  return {
+    "content-type": "application/json",
+    "x-signature-ed25519": toHex(signature),
+    "x-signature-timestamp": timestamp,
+  };
+}
+
+beforeAll(async () => {
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+  const keyPair = (await crypto.subtle.generateKey({ name: "Ed25519" }, true, [
+    "sign",
+    "verify",
+  ])) as CryptoKeyPair;
+  privateKey = keyPair.privateKey;
+  const publicKey = toHex(await crypto.subtle.exportKey("raw", keyPair.publicKey));
+
+  setChatSdkTestHooks({ disableDiscordGateway: true });
+  process.env.CHAT_SDK_ENABLED = "true";
+  process.env.CHAT_SDK_ADAPTERS = JSON.stringify({
+    discord: { botToken: "discord-test-token", publicKey, applicationId: "1234567890" },
+  });
+  process.env.CHAT_SDK_API_URL_OVERRIDES = JSON.stringify({
+    discord: `http://127.0.0.1:${await getFreePort()}/api/v10`,
+  });
+  await startChatSdk();
+  await stopChatRelayWatcher();
+});
+
+afterAll(async () => {
+  await stopChatSdk();
+  setChatSdkTestHooks({});
+  restoreEnv();
+  closeDb();
+  await removeDbFiles();
+});
+
+describe("Chat SDK Discord interactions webhook", () => {
+  test("the adapter starts without the Gateway loop", () => {
+    const health = getChatSdkHealth().discord;
+    expect(health?.status).toBe("ok");
+    expect(health?.gateway).toBeUndefined();
+  });
+
+  test("an unsigned interaction is rejected with 401", async () => {
+    const response = await postChatWebhook("discord", JSON.stringify({ type: 1 }), {
+      "content-type": "application/json",
+    });
+    expect(response.status).toBe(401);
+  });
+
+  test("a body that does not match its signature is rejected with 401", async () => {
+    const headers = await signedHeaders(JSON.stringify({ type: 1 }));
+    const response = await postChatWebhook("discord", JSON.stringify({ type: 2 }), headers);
+    expect(response.status).toBe(401);
+  });
+
+  test("a signed PING is answered with a PONG", async () => {
+    const body = JSON.stringify({ type: 1 });
+    const response = await postChatWebhook("discord", body, await signedHeaders(body));
+    expect(response.status).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ type: 1 });
+  });
+
+  // Last in the file: it stops the runtime. `afterAll` stops it again, a no-op.
+  test("health shows the Gateway loop while it runs and drops it on shutdown", async () => {
+    // A stub listener: the real one logs in to Discord. Its window ends only on abort.
+    const gateway: DiscordGatewayListener = {
+      async startGatewayListener(options, _durationMs, signal) {
+        options.waitUntil?.(
+          new Promise<void>((resolve) => signal?.addEventListener("abort", () => resolve())),
+        );
+        return new Response("{}", { status: 200 });
+      },
+    };
+    startDiscordGateway(gateway);
+    expect(getChatSdkHealth().discord?.gateway?.state).toBe("running");
+
+    await stopChatSdk();
+    expect(getChatSdkHealth().discord).toBeUndefined();
+    expect(getDiscordGatewayHealth()).toBeUndefined();
+  });
+});

package/src/tests/chat-sdk-fields-sync.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { CHAT_SDK_ADAPTER_DEFS, chatSdkSecretKey } from "../../apps/ui/src/lib/chat-sdk-fields";
+import {
+  CHAT_SDK_ADAPTER_FIELDS,
+  CHAT_SDK_ADAPTER_NAMES,
+  SlackAdapterSchema,
+  TeamsAdapterSchema,
+  TelegramAdapterSchema,
+} from "../integrations/chat-sdk/schema";
+
+/*
+ * The dashboard keeps a plain field list for the Chat SDK card because it
+ * cannot import the API's zod schemas. This test keeps the two equal.
+ */
+describe("Chat SDK field list sync (UI vs API schema)", () => {
+  test("the UI lists the same adapters in the same order", () => {
+    expect(CHAT_SDK_ADAPTER_DEFS.map((def) => def.name)).toEqual([...CHAT_SDK_ADAPTER_NAMES]);
+  });
+
+  test("every adapter has the same field names", () => {
+    for (const def of CHAT_SDK_ADAPTER_DEFS) {
+      expect(def.fields.map((field) => field.key).sort()).toEqual(
+        [...CHAT_SDK_ADAPTER_FIELDS[def.name]].sort(),
+      );
+    }
+  });
+
+  test("select options match the schema enums", () => {
+    const enums: Record<string, readonly string[]> = {
+      "telegram.mode": TelegramAdapterSchema.shape.mode.unwrap().options,
+      "slack.mode": SlackAdapterSchema.shape.mode.unwrap().options,
+      "teams.appType": TeamsAdapterSchema.shape.appType.unwrap().options,
+    };
+    const selects: Array<readonly [string, string[] | undefined]> = CHAT_SDK_ADAPTER_DEFS.flatMap(
+      (def) =>
+        def.fields
+          .filter((field) => field.kind === "select")
+          .map((field) => [`${def.name}.${field.key}`, field.options] as const),
+    );
+    expect(selects.map(([path]) => path).sort()).toEqual(Object.keys(enums).sort());
+    for (const [path, options] of selects) {
+      expect(options).toEqual([...(enums[path] ?? [])]);
+    }
+  });
+
+  test("secret rows are named CHAT_SDK_<ADAPTER>_<FIELD>", () => {
+    expect(chatSdkSecretKey("telegram", "botToken")).toBe("CHAT_SDK_TELEGRAM_BOT_TOKEN");
+    expect(chatSdkSecretKey("teams", "appPassword")).toBe("CHAT_SDK_TEAMS_APP_PASSWORD");
+  });
+});

package/src/tests/chat-sdk-harness.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared harness for Chat SDK tests that drive platform webhooks through the
+ * real route. Telegram runs against the fake Bot API
+ * (`scripts/dev/telegram-bot-api-mock.ts`); `postChatWebhook` and
+ * `snapshotChatSdkEnv` serve the Slack and Teams tests too.
+ */
+import { expect } from "bun:test";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  startTelegramBotApiMock,
+  type TelegramBotApiMock,
+} from "../../scripts/dev/telegram-bot-api-mock";
+import { handleWebhooks } from "../http/webhooks";
+import { drainBackground } from "../integrations/chat-sdk/background";
+import { startChatSdk, stopChatSdk } from "../integrations/chat-sdk/runtime";
+import { flushAllChatBuffers } from "../integrations/chat-sdk/thread-buffer";
+
+export const TELEGRAM_SECRET = "chat-sdk-test-secret";
+const ENV_KEYS = [
+  "CHAT_SDK_ENABLED",
+  "CHAT_SDK_ADAPTERS",
+  "CHAT_SDK_API_URL_OVERRIDES",
+  "CHAT_SDK_BUFFER_MS",
+  "SLACK_DISABLE",
+];
+
+/** Save the Chat SDK env keys; the returned function restores them. */
+export function snapshotChatSdkEnv(): () => void {
+  const saved = new Map(ENV_KEYS.map((key) => [key, process.env[key]]));
+  return () => {
+    for (const [key, value] of saved) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  };
+}
+
+let nextUpdateId = 950_000;
+let nextMessageId = 5_000;
+
+export interface TelegramHarness {
+  mock: TelegramBotApiMock;
+  stop: () => Promise<void>;
+}
+
+/** Start the mock Bot API and a webhook-mode Telegram adapter pointed at it. */
+export async function startTelegramHarness(bufferMs = 60_000): Promise<TelegramHarness> {
+  const restoreEnv = snapshotChatSdkEnv();
+  const mock = startTelegramBotApiMock();
+  process.env.CHAT_SDK_ENABLED = "true";
+  process.env.CHAT_SDK_ADAPTERS = JSON.stringify({
+    telegram: { botToken: "t", secretToken: TELEGRAM_SECRET, mode: "webhook" },
+  });
+  process.env.CHAT_SDK_API_URL_OVERRIDES = JSON.stringify({ telegram: mock.url });
+  process.env.CHAT_SDK_BUFFER_MS = String(bufferMs);
+  await startChatSdk();
+  return {
+    mock,
+    stop: async () => {
+      await stopChatSdk();
+      mock.stop();
+      restoreEnv();
+    },
+  };
+}
+
+export interface TelegramChat {
+  id: number;
+  type: "private" | "group";
+}
+
+/** A Telegram `message` update from a human in `chat`. */
+export function telegramUpdate(
+  chat: TelegramChat,
+  text: string,
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const from = { id: 777_001, is_bot: false, first_name: "Tester", username: "tester" };
+  return {
+    update_id: ++nextUpdateId,
+    message: {
+      message_id: ++nextMessageId,
+      date: Math.floor(Date.now() / 1000),
+      chat:
+        chat.type === "private"
+          ? { id: chat.id, type: "private", first_name: "Tester" }
+          : { id: chat.id, type: "group", title: "Swarm group" },
+      from,
+      ...(text ? { text } : {}),
+      ...extra,
+    },
+  };
+}
+
+export interface ChatWebhookResponse {
+  status: number;
+  body: string;
+}
+
+/** POST a raw body to `/api/integrations/chat/{adapter}/webhook` through `handleWebhooks`. */
+export async function postChatWebhook(
+  adapter: string,
+  body: string,
+  headers: Record<string, string>,
+): Promise<ChatWebhookResponse> {
+  const path = `/api/integrations/chat/${adapter}/webhook`;
+  const req = {
+    method: "POST",
+    url: path,
+    headers: Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v])),
+    rawHeaders: Object.entries(headers).flat(),
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.from(body);
+    },
+  } as unknown as IncomingMessage;
+  const captured = { status: 0, body: "" };
+  const res = {
+    headersSent: false,
+    writeHead(status: number) {
+      captured.status = status;
+      return this;
+    },
+    end(chunk?: string | Buffer) {
+      if (chunk) captured.body = chunk.toString();
+      return this;
+    },
+  } as unknown as ServerResponse;
+  expect(await handleWebhooks(req, res, path.split("/").filter(Boolean))).toBe(true);
+  return captured;
+}
+
+/** POST one update to the Telegram webhook and wait for the handler work. */
+export async function postTelegramUpdate(update: unknown): Promise<void> {
+  const response = await postChatWebhook("telegram", JSON.stringify(update), {
+    "content-type": "application/json",
+    "x-telegram-bot-api-secret-token": TELEGRAM_SECRET,
+  });
+  expect(response.status).toBe(200);
+  expect(await drainBackground(5_000)).toBe(true);
+}
+
+/** Flush every waiting thread (no timer wait) and wait for the resulting work. */
+export async function flushChatBuffers(): Promise<void> {
+  await flushAllChatBuffers();
+  expect(await drainBackground(5_000)).toBe(true);
+}

package/src/tests/chat-sdk-inbound.test.ts

@@ -0,0 +1,363 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  closeDb,
+  createAgent,
+  getDbClient,
+  getTaskAttachments,
+  getTaskById,
+  initDb,
+  upsertKv,
+} from "../be/db";
+import { resetFileStorageProviderForTests } from "../fs/registry";
+import { drainBackground } from "../integrations/chat-sdk/background";
+import { CHAT_CHANNELS_NAMESPACE, routeChatMessage } from "../integrations/chat-sdk/router";
+import { getChatInstance } from "../integrations/chat-sdk/runtime";
+import { isChatThreadBuffered } from "../integrations/chat-sdk/thread-buffer";
+import { chatSdkContextKey } from "../tasks/context-key";
+import type { Agent } from "../types";
+import {
+  flushChatBuffers,
+  postChatWebhook,
+  postTelegramUpdate,
+  startTelegramHarness,
+  TELEGRAM_SECRET,
+  type TelegramChat,
+  type TelegramHarness,
+  telegramUpdate,
+} from "./chat-sdk-harness";
+
+const TEST_DB_PATH = "./test-chat-sdk-inbound.sqlite";
+const ENV_KEYS = ["AGENT_FS_LOCAL_DIR", "AGENT_FS_API_URL", "STEERING_ENABLED"];
+const savedEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]]));
+
+let harness: TelegramHarness;
+let lead: Agent;
+let worker: Agent;
+let fsDir: string;
+/** `ctx.skipped` length seen by every DM / subscribed delivery (always 0 under `concurrent`). */
+const skippedCounts: number[] = [];
+
+type TaskRow = {
+  id: string;
+  agentId: string | null;
+  task: string;
+  status: string;
+  routingReason: string | null;
+};
+
+async function chatTasks(chatId: number): Promise<TaskRow[]> {
+  return getDbClient().query<TaskRow>(
+    `SELECT id, agentId, task, status, routing_reason AS routingReason FROM agent_tasks
+       WHERE source = 'chat' AND contextKey = ? ORDER BY createdAt, rowid`,
+    [chatSdkContextKey(`telegram:${chatId}`)],
+  );
+}
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+}
+
+beforeAll(async () => {
+  await removeDbFiles();
+  fsDir = await mkdtemp(join(tmpdir(), "chat-sdk-inbound-fs-"));
+  process.env.AGENT_FS_LOCAL_DIR = fsDir;
+  delete process.env.AGENT_FS_API_URL;
+  process.env.STEERING_ENABLED = "true";
+  resetFileStorageProviderForTests();
+  initDb(TEST_DB_PATH);
+  lead = await createAgent({
+    id: crypto.randomUUID(),
+    name: "ChatInboundLead",
+    isLead: true,
+    status: "idle",
+  });
+  worker = await createAgent({
+    id: crypto.randomUUID(),
+    name: "ChatInboundWorker",
+    isLead: false,
+    status: "idle",
+  });
+  harness = await startTelegramHarness();
+  const chat = getChatInstance("telegram");
+  expect(chat).toBeDefined();
+  chat!.onDirectMessage((_thread, _message, _channel, ctx) => {
+    skippedCounts.push(ctx?.skipped?.length ?? 0);
+  });
+  chat!.onSubscribedMessage((_thread, _message, ctx) => {
+    skippedCounts.push(ctx?.skipped?.length ?? 0);
+  });
+});
+
+afterAll(async () => {
+  await harness.stop();
+  closeDb();
+  await removeDbFiles();
+  await rm(fsDir, { recursive: true, force: true });
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  resetFileStorageProviderForTests();
+});
+
+beforeEach(() => {
+  process.env.CHAT_SDK_BUFFER_MS = "60000";
+});
+
+const dm = (id: number): TelegramChat => ({ id, type: "private" });
+const group = (id: number): TelegramChat => ({ id, type: "group" });
+
+describe("Chat SDK inbound pipeline", () => {
+  test("two messages inside the buffer window become one task", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2001), "first part of the request"));
+    await postTelegramUpdate(telegramUpdate(dm(2001), "second part of the request"));
+    expect(await chatTasks(2001)).toHaveLength(0);
+
+    await flushChatBuffers();
+    const tasks = await chatTasks(2001);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]!.task).toContain("[Thread follow-up: 2 message(s) buffered]");
+    expect(tasks[0]!.task).toContain("first part of the request");
+    expect(tasks[0]!.task).toContain("second part of the request");
+    expect(tasks[0]!.agentId).toBe(lead.id);
+    // `concurrent` never batches deliveries, so the SDK skips nothing.
+    expect(skippedCounts.length).toBeGreaterThanOrEqual(2);
+    expect(skippedCounts.every((count) => count === 0)).toBe(true);
+  });
+
+  test("!now flushes the thread at once", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2002), "!now ship the hotfix"));
+    const tasks = await chatTasks(2002);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]!.task).toBe("ship the hotfix");
+  });
+
+  test("swarm#<uuid> routes to that agent", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2003), `swarm#${worker.id} build the parser`));
+    await flushChatBuffers();
+    const tasks = await chatTasks(2003);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]!.agentId).toBe(worker.id);
+    expect(tasks[0]!.task).toBe("build the parser");
+  });
+
+  test("a KV channel mapping routes to the pinned agent", async () => {
+    await upsertKv({
+      namespace: CHAT_CHANNELS_NAMESPACE,
+      key: "telegram:2004",
+      value: { agentId: worker.id },
+      valueType: "json",
+    });
+    await postTelegramUpdate(telegramUpdate(dm(2004), "summarize the logs"));
+    await flushChatBuffers();
+    const tasks = await chatTasks(2004);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]!.agentId).toBe(worker.id);
+    expect(tasks[0]!.routingReason).toBe("human_pinned");
+  });
+
+  test("a workflow channel mapping fires only for a mention or DM, not a subscribed reply", async () => {
+    await upsertKv({
+      namespace: CHAT_CHANNELS_NAMESPACE,
+      key: "telegram:-2008",
+      value: { workflowId: "wf-mapped" },
+      valueType: "json",
+    });
+    const ctx = {
+      adapter: "telegram" as const,
+      channelId: "telegram:-2008",
+      threadId: "telegram:-2008",
+    };
+    expect(
+      await routeChatMessage("run it", { ...ctx, botMentioned: true, isDirectMessage: false }),
+    ).toEqual({ kind: "workflow", workflowId: "wf-mapped" });
+    expect(
+      await routeChatMessage("run it", { ...ctx, botMentioned: false, isDirectMessage: true }),
+    ).toEqual({ kind: "workflow", workflowId: "wf-mapped" });
+    // A plain reply in the subscribed thread after the first run: no owner, no mention.
+    expect(
+      await routeChatMessage("thanks", { ...ctx, botMentioned: false, isDirectMessage: false }),
+    ).toBeNull();
+  });
+
+  async function steeringRows(taskId: string) {
+    return getDbClient().query<{ body: string; source: string }>(
+      "SELECT body, source FROM task_steering_messages WHERE task_id = ?",
+      [taskId],
+    );
+  }
+
+  test("a group reply to an in-progress lead task steers it instead of creating a task", async () => {
+    await postTelegramUpdate(telegramUpdate(group(-2005), "@swarm_test_bot draft the report"));
+    await flushChatBuffers();
+    const [first] = await chatTasks(-2005);
+    expect(first?.agentId).toBe(lead.id);
+    await getDbClient().run("UPDATE agent_tasks SET status = 'in_progress' WHERE id = ?", [
+      first!.id,
+    ]);
+
+    const acksBefore = harness.mock.calls.filter((call) =>
+      /^send(Rich)?Message$/.test(call.method),
+    ).length;
+    await postTelegramUpdate(telegramUpdate(group(-2005), "also add the charts"));
+    await flushChatBuffers();
+
+    expect(await chatTasks(-2005)).toHaveLength(1);
+    expect(await steeringRows(first!.id)).toEqual([
+      { body: "also add the charts", source: "chat" },
+    ]);
+    expect(
+      harness.mock.calls.filter((call) => /^send(Rich)?Message$/.test(call.method)).length,
+    ).toBe(acksBefore + 1);
+  });
+
+  test("a Telegram private-chat DM steers too (DMs never reach onSubscribedMessage)", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2006), "start the migration"));
+    await flushChatBuffers();
+    const [first] = await chatTasks(2006);
+    await getDbClient().run("UPDATE agent_tasks SET status = 'in_progress' WHERE id = ?", [
+      first!.id,
+    ]);
+
+    await postTelegramUpdate(telegramUpdate(dm(2006), "skip the staging step"));
+    await flushChatBuffers();
+
+    expect(await chatTasks(2006)).toHaveLength(1);
+    expect(await steeringRows(first!.id)).toEqual([
+      { body: "skip the staging step", source: "chat" },
+    ]);
+  });
+
+  test("a reply while the task is still pending becomes a follow-up that depends on it", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2007), "plan the release"));
+    await flushChatBuffers();
+    const [first] = await chatTasks(2007);
+    expect(first?.status).toBe("pending");
+
+    await postTelegramUpdate(telegramUpdate(dm(2007), "include the changelog"));
+    await flushChatBuffers();
+
+    const tasks = await chatTasks(2007);
+    expect(tasks).toHaveLength(2);
+    const followUp = await getTaskById(tasks[1]!.id);
+    expect(followUp?.dependsOn).toEqual([first!.id]);
+    expect(followUp?.parentTaskId).toBe(first!.id);
+    expect(followUp?.task).toContain("include the changelog");
+  });
+
+  test("a document attachment becomes a task attachment and a [File: ...] line", async () => {
+    const bytes = new TextEncoder().encode("meeting notes\n");
+    harness.mock.addFile("documents/notes.txt", bytes);
+    await postTelegramUpdate(
+      telegramUpdate(dm(2008), "", {
+        caption: "see the attached notes",
+        document: {
+          file_id: "documents/notes.txt",
+          file_unique_id: "notes-unique",
+          file_name: "notes.txt",
+          mime_type: "text/plain",
+          file_size: bytes.byteLength,
+        },
+      }),
+    );
+    await flushChatBuffers();
+
+    const tasks = await chatTasks(2008);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]!.status).toBe("pending");
+    expect(tasks[0]!.task).toContain("see the attached notes");
+    expect(tasks[0]!.task).toMatch(/\[File: notes\.txt \(text\/plain, 14 B\) id=2008_\d+-1\]/);
+    const attachments = await getTaskAttachments(tasks[0]!.id);
+    expect(attachments).toHaveLength(1);
+    expect(attachments[0]).toMatchObject({ name: "notes.txt", sizeBytes: bytes.byteLength });
+  });
+
+  test("overlapping timer flushes of one thread create their tasks in order", async () => {
+    // Hold the first message's file download so its flush is still running
+    // when the second message's timer flush starts.
+    const bytes = new TextEncoder().encode("held file\n");
+    harness.mock.addFile("documents/held.txt", bytes);
+    let releaseDownload!: () => void;
+    const downloadHeld = new Promise<void>((resolve) => {
+      releaseDownload = resolve;
+    });
+    let downloadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      downloadStarted = resolve;
+    });
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+      const url = input instanceof Request ? input.url : String(input);
+      if (url.includes("/file/bot") && url.endsWith("documents/held.txt")) {
+        downloadStarted();
+        await downloadHeld;
+      }
+      return realFetch(input, init);
+    }) as typeof fetch;
+    process.env.CHAT_SDK_BUFFER_MS = "50";
+    const threadId = "telegram:2010";
+    try {
+      await postTelegramUpdate(
+        telegramUpdate(dm(2010), "", {
+          caption: "first: read the held file",
+          document: {
+            file_id: "documents/held.txt",
+            file_unique_id: "held-unique",
+            file_name: "held.txt",
+            mime_type: "text/plain",
+            file_size: bytes.byteLength,
+          },
+        }),
+      );
+      await started;
+      // A longer window for the second message, so the wait below sees it buffered.
+      process.env.CHAT_SDK_BUFFER_MS = "300";
+
+      // Not `postTelegramUpdate`: its background drain would wait on the held download.
+      const response = await postChatWebhook(
+        "telegram",
+        JSON.stringify(telegramUpdate(dm(2010), "second: then summarize it")),
+        {
+          "content-type": "application/json",
+          "x-telegram-bot-api-secret-token": TELEGRAM_SECRET,
+        },
+      );
+      expect(response.status).toBe(200);
+      const waitFor = async (condition: () => boolean) => {
+        const deadline = Date.now() + 3_000;
+        while (!condition() && Date.now() < deadline) await Bun.sleep(5);
+        expect(condition()).toBe(true);
+      };
+      await waitFor(() => isChatThreadBuffered(threadId));
+      await waitFor(() => !isChatThreadBuffered(threadId));
+      // The second flush has fired. Without the per-thread chain it would
+      // create its task now, before the first one.
+      await Bun.sleep(200);
+      expect(await chatTasks(2010)).toHaveLength(0);
+
+      releaseDownload();
+      expect(await drainBackground(5_000)).toBe(true);
+    } finally {
+      releaseDownload();
+      globalThis.fetch = realFetch;
+    }
+
+    const tasks = await chatTasks(2010);
+    expect(tasks).toHaveLength(2);
+    expect(tasks[0]!.task).toContain("first: read the held file");
+    expect(tasks[1]!.task).toContain("second: then summarize it");
+    const second = await getTaskById(tasks[1]!.id);
+    expect(second?.dependsOn).toEqual([tasks[0]!.id]);
+  });
+
+  test("a message in an unmapped group that does not mention the bot is ignored", async () => {
+    await postTelegramUpdate(telegramUpdate(group(-2009), "just chatting"));
+    await flushChatBuffers();
+    expect(await chatTasks(-2009)).toHaveLength(0);
+  });
+});