@desplega.ai/agent-swarm 2.5.0 → 2.5.2

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

@@ -7,6 +7,7 @@ import {
   closeDb,
   completeTask,
   createAgent,
+  createScheduledTask,
   createTaskExtended,
   createUser,
   getDbClient,
@@ -20,10 +21,12 @@ import {
 import { linkIdentity } from "../be/users";
 import { resetFileStorageProviderForTests } from "../fs/registry";
 import { drainBackground } from "../integrations/chat-sdk/background";
-import { formatChatRelayText } from "../integrations/chat-sdk/relay";
+import { CHAT_CHANNEL_SETTINGS_NAMESPACE } from "../integrations/chat-sdk/reactions";
+import { formatChatRelayText, formatChatTaskTag } from "../integrations/chat-sdk/relay";
 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 { createStandaloneScheduleTask } from "../scheduler/schedule-task";
 import { chatSdkContextKey } from "../tasks/context-key";
 import { registerDeferTaskTool } from "../tools/defer-task";
 import type { Agent } from "../types";
@@ -144,6 +147,25 @@ function buildDeferTaskTool(): DeferTaskTool {
 const dm = (id: number): TelegramChat => ({ id, type: "private" });
 const group = (id: number): TelegramChat => ({ id, type: "group" });
 
+const messageIdOf = (update: Record<string, unknown>) =>
+  (update.message as { message_id: number }).message_id;
+
+/** Every `setMessageReaction` call on one message, as the emoji it set (`""` = cleared). */
+function reactionsOn(chatId: number, update: Record<string, unknown>): string[] {
+  return harness.mock.calls
+    .filter((call) => call.method === "setMessageReaction")
+    .map((call) => call.body as { chat_id: unknown; message_id: unknown; reaction: unknown })
+    .filter(
+      (body) =>
+        String(body.chat_id) === String(chatId) && Number(body.message_id) === messageIdOf(update),
+    )
+    .map((body) => {
+      const reaction =
+        typeof body.reaction === "string" ? JSON.parse(body.reaction) : body.reaction;
+      return (reaction as Array<{ emoji?: string }>).map((r) => r.emoji ?? "").join("");
+    });
+}
+
 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"));
@@ -233,19 +255,101 @@ describe("Chat SDK inbound pipeline", () => {
       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"));
+    const sendCount = () =>
+      harness.mock.calls.filter((call) => /^send(Rich)?Message$/.test(call.method)).length;
+    const sendsBefore = sendCount();
+    const steer = telegramUpdate(group(-2005), "also add the charts");
+    await postTelegramUpdate(steer);
     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);
+    // A reaction acknowledges the steering message; no text reply.
+    expect(reactionsOn(-2005, steer)).toEqual(["✍"]);
+    expect(sendCount()).toBe(sendsBefore);
+  });
+
+  test("a channel that opts into text acks also gets the steering reply", async () => {
+    await upsertKv({
+      namespace: CHAT_CHANNEL_SETTINGS_NAMESPACE,
+      key: "telegram:-2015",
+      value: { textAcks: true },
+      valueType: "json",
+    });
+    await postTelegramUpdate(telegramUpdate(group(-2015), "@swarm_test_bot draft the report"));
+    await flushChatBuffers();
+    const [first] = await chatTasks(-2015);
+    await getDbClient().run("UPDATE agent_tasks SET status = 'in_progress' WHERE id = ?", [
+      first!.id,
+    ]);
+
+    const steer = telegramUpdate(group(-2015), "also add the charts");
+    await postTelegramUpdate(steer);
+
+    expect(reactionsOn(-2015, steer)).toEqual(["✍"]);
+    const sends = harness.mock.calls.filter((call) => /^send(Rich)?Message$/.test(call.method));
+    // The acknowledgement replies to the steering message.
+    expect(sends.at(-1)?.body.reply_parameters).toEqual({
+      message_id: messageIdOf(steer),
+      allow_sending_without_reply: true,
+    });
+  });
+
+  test("an ask gets one reaction at a time; earlier buffered messages are cleared at flush", async () => {
+    const firstPart = telegramUpdate(dm(2016), "first part");
+    const secondPart = telegramUpdate(dm(2016), "second part");
+    await postTelegramUpdate(firstPart);
+    expect(reactionsOn(2016, firstPart)).toEqual(["👀"]);
+    await postTelegramUpdate(secondPart);
+    await flushChatBuffers();
+
+    expect(await chatTasks(2016)).toHaveLength(1);
+    // The task answers the newest message, which keeps 👀; the earlier one is cleared.
+    expect(reactionsOn(2016, secondPart)).toEqual(["👀"]);
+    expect(reactionsOn(2016, firstPart)).toEqual(["👀", ""]);
+
+    const quick = telegramUpdate(dm(2017), "!now ship it");
+    await postTelegramUpdate(quick);
+    expect(reactionsOn(2017, quick)).toEqual(["⚡"]);
+  });
+
+  test("a REACTION_INVALID answer is logged and the ask still becomes a task", async () => {
+    const warn = spyOn(console, "warn");
+    harness.mock.failReactions(1);
+    try {
+      const ask = telegramUpdate(dm(2018), "!now plan the sprint");
+      await postTelegramUpdate(ask);
+      expect(await chatTasks(2018)).toHaveLength(1);
+      expect(reactionsOn(2018, ask)).toHaveLength(1);
+      expect(
+        warn.mock.calls.some((args) => String(args[0]).includes("Could not set the now reaction")),
+      ).toBe(true);
+    } finally {
+      harness.mock.failReactions(0);
+      warn.mockRestore();
+    }
+  });
+
+  test("two asks back to back each anchor to their own message, not the parent's", async () => {
+    const firstAsk = telegramUpdate(group(-2010), "@swarm_test_bot !now summarize the PR");
+    await postTelegramUpdate(firstAsk);
+    const secondAsk = telegramUpdate(group(-2010), "@swarm_test_bot !now and list the risks");
+    await postTelegramUpdate(secondAsk);
+    await flushChatBuffers();
+
+    const rows = await chatTasks(-2010);
+    expect(rows).toHaveLength(2);
+    const [first, second] = await Promise.all(rows.map((row) => getTaskById(row.id)));
+    const idOf = (update: Record<string, unknown>) =>
+      `-2010:${(update.message as { message_id: number }).message_id}`;
+    expect(first?.mentionMessageId).toBe(idOf(firstAsk));
+    // The second task is a child of the first; `createTask` would copy the
+    // parent's anchor if inbound did not set its own.
+    expect(second?.parentTaskId).toBe(first!.id);
+    expect(second?.mentionMessageId).toBe(idOf(secondAsk));
+    expect(second?.mentionChannelId).toBeTruthy();
   });
 
   test("a Telegram private-chat DM steers too (DMs never reach onSubscribedMessage)", async () => {
@@ -282,6 +386,52 @@ describe("Chat SDK inbound pipeline", () => {
     expect(followUp?.task).toContain("include the changelog");
   });
 
+  test("a deferred wake-up is the thread's chat task: steering, a follow-up dependency and /cancel reach it", async () => {
+    await postTelegramUpdate(telegramUpdate(dm(2040), "check the deploy"));
+    await flushChatBuffers();
+    const [first] = await chatTasks(2040);
+    await completeTask(first!.id, "Deferred.", { deferredAt: new Date().toISOString() });
+    const schedule = await createScheduledTask({
+      name: `deferred-${first!.id.slice(0, 8)}-${crypto.randomUUID()}`,
+      taskTemplate: "Check the deploy and answer.",
+      targetType: "agent-task",
+      scheduleType: "one_time",
+      nextRunAt: new Date().toISOString(),
+      targetAgentId: lead.id,
+      createdByAgentId: lead.id,
+      taskType: "deferred",
+      parentTaskId: first!.id,
+    });
+    const wakeUp = await createStandaloneScheduleTask(schedule);
+    expect(wakeUp.source).toBe("schedule");
+    expect(wakeUp.contextKey).toBe(chatSdkContextKey("telegram:2040"));
+
+    // In progress: a plain message steers the wake-up.
+    await startTask(wakeUp.id);
+    await postTelegramUpdate(telegramUpdate(dm(2040), "use the staging cluster"));
+    await flushChatBuffers();
+    expect(await chatTasks(2040)).toHaveLength(1);
+    expect(await steeringRows(wakeUp.id)).toEqual([
+      { body: "use the staging cluster", source: "chat" },
+    ]);
+
+    // Pending: a new message becomes a follow-up that waits for it.
+    await getDbClient().run("UPDATE agent_tasks SET status = 'pending' WHERE id = ?", [wakeUp.id]);
+    await postTelegramUpdate(telegramUpdate(dm(2040), "and the canary"));
+    await flushChatBuffers();
+    const tasks = await chatTasks(2040);
+    expect(tasks).toHaveLength(2);
+    expect((await getTaskById(tasks[1]!.id))?.dependsOn).toEqual([wakeUp.id]);
+
+    // /cancel stops the follow-up and the wake-up.
+    const cancel = telegramUpdate(dm(2040), "/cancel", {
+      entities: [{ type: "bot_command", offset: 0, length: "/cancel".length }],
+    });
+    await postTelegramUpdate(cancel);
+    expect((await getTaskById(wakeUp.id))?.status).toBe("cancelled");
+    expect((await getTaskById(tasks[1]!.id))?.status).toBe("cancelled");
+  });
+
   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);
@@ -451,7 +601,11 @@ describe("Chat SDK requester and group addressing", () => {
     const deferred = await getTaskById(task!.id);
     expect(deferred?.output).toMatch(new RegExp(`at ${madrid}$`));
     expect(deferred?.output).not.toContain("UTC");
-    expect(formatChatRelayText(deferred!)).toBe(deferred!.output!);
+    // The relay posts the placeholder text after the task tag (here the trigger
+    // drops it: a deferral posts nothing).
+    expect(formatChatRelayText(deferred!)).toBe(
+      `${formatChatTaskTag(deferred!)}\n\n${deferred!.output!}`,
+    );
   });
 
   test("an unknown sender gets no requester and lands in the Unmapped tracker", async () => {

package/src/tests/chat-sdk-outbound-files.test.ts

@@ -25,7 +25,11 @@ import {
 import { recordTaskAttachmentUpload } from "../be/task-attachment-store";
 import { getFileStorageProvider, resetFileStorageProviderForTests } from "../fs/registry";
 import { formatUnsentFilesNote, telegramAttachmentType } from "../integrations/chat-sdk/outbound";
-import { processPendingChatRelays, stopChatRelayWatcher } from "../integrations/chat-sdk/relay";
+import {
+  formatChatTaskTag,
+  processPendingChatRelays,
+  stopChatRelayWatcher,
+} from "../integrations/chat-sdk/relay";
 import { chatSdkContextKey } from "../tasks/context-key";
 import { registerChatPostTool } from "../tools/chat-post";
 import { registerChatReplyTool } from "../tools/chat-reply";
@@ -646,7 +650,10 @@ describe("relay of output attachments", () => {
       expect.stringMatching(/^send(Rich)?Message$/),
       "sendDocument",
     ]);
-    expect(textOf(calls[0]!.body)).toBe("Done, report attached.");
+    // The line-leading tag is escaped so Telegram does not render it as a heading.
+    expect(textOf(calls[0]!.body)).toBe(
+      `\\${formatChatTaskTag(task, lead.name)}\n\nDone, report attached.`,
+    );
     expect((calls[1]!.body.document as TelegramMockFilePart).filename).toBe("result.pdf");
   });
 });

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

@@ -5,6 +5,7 @@ import {
   closeDb,
   completeTask,
   createAgent,
+  createScheduledTask,
   createTaskExtended,
   failTask,
   getDbClient,
@@ -19,13 +20,16 @@ import { cleanExtensionTmpRoot, loadExtension } from "../extensions/loader";
 import { initExtensionPostBridge, teardownExtensionPostBridge } from "../extensions/post-bridge";
 import { splitChatMessage } from "../integrations/chat-sdk/limits";
 import {
+  formatChatRelayMessages,
   formatChatRelayText,
   processPendingChatRelays,
   RELAY_GIVE_UP_AFTER_MS,
   stopChatRelayWatcher,
+  TELEGRAM_FOLD_CHARS,
 } from "../integrations/chat-sdk/relay";
+import { createStandaloneScheduleTask } from "../scheduler/schedule-task";
 import { chatSdkContextKey } from "../tasks/context-key";
-import { createResumeFollowUp } from "../tasks/worker-follow-up";
+import { createResumeFollowUp, createWorkerTaskFollowUp } from "../tasks/worker-follow-up";
 import type { Agent, AgentTask } from "../types";
 import { startTelegramHarness, type TelegramHarness } from "./chat-sdk-harness";
 import { loadBundleFixture } from "./fixtures/extensions/load";
@@ -82,13 +86,19 @@ function sentText(body: Record<string, unknown>): string {
 
 async function createChatTask(
   chatId: number,
-  options: { source?: "chat" | "system"; taskType?: string } = {},
+  options: { source?: "chat" | "system"; taskType?: string; askMessageId?: number } = {},
 ): Promise<AgentTask> {
   return createTaskExtended(`chat task for ${chatId}`, {
     agentId: lead.id,
     source: options.source ?? "chat",
     taskType: options.taskType,
     contextKey: chatSdkContextKey(`telegram:${chatId}`),
+    ...(options.askMessageId !== undefined
+      ? {
+          mentionMessageId: `${chatId}:${options.askMessageId}`,
+          mentionChannelId: `telegram:${chatId}`,
+        }
+      : {}),
   });
 }
 
@@ -122,14 +132,45 @@ beforeEach(() => {
 });
 
 describe("chat relay text", () => {
-  test("status prefix for failed and cancelled tasks, default for an empty completion", () => {
-    const base = { output: undefined, failureReason: undefined } as unknown as AgentTask;
-    expect(formatChatRelayText({ ...base, status: "completed" })).toBe("Task completed.");
-    expect(formatChatRelayText({ ...base, status: "completed", output: "done" })).toBe("done");
-    expect(formatChatRelayText({ ...base, status: "failed", failureReason: "boom" })).toBe(
-      "**Task failed.**\n\nboom",
+  test("task tag first, status line for failed and cancelled, default for an empty completion", () => {
+    const base = {
+      id: "a3f2b1c9-0000-4000-8000-000000000000",
+      output: undefined,
+      failureReason: undefined,
+    } as unknown as AgentTask;
+    const tag = "#a3f2b1c9 · Coder";
+    expect(formatChatRelayText({ ...base, status: "completed" }, "Coder")).toBe(
+      `${tag}\n\nTask completed.`,
+    );
+    expect(formatChatRelayText({ ...base, status: "completed", output: "done" }, "Coder")).toBe(
+      `${tag}\n\ndone`,
+    );
+    expect(formatChatRelayText({ ...base, status: "failed", failureReason: "boom" }, "Coder")).toBe(
+      `${tag}\n**Task failed.**\n\nboom`,
+    );
+    expect(formatChatRelayText({ ...base, status: "cancelled" })).toBe(
+      "#a3f2b1c9\n**Task cancelled.**",
     );
-    expect(formatChatRelayText({ ...base, status: "cancelled" })).toBe("**Task cancelled.**");
+  });
+
+  test("a long Telegram answer folds into <details>; other adapters and short answers do not", () => {
+    const base = { id: "a3f2b1c9-0000-4000-8000-000000000000", status: "completed" };
+    const long = `The short answer is yes.\n\n${"detail line\n".repeat(200)}`.trim();
+    const task = { ...base, output: long } as unknown as AgentTask;
+    expect(long.length).toBeGreaterThan(TELEGRAM_FOLD_CHARS);
+
+    const [message, ...more] = formatChatRelayMessages(task, "telegram", "Coder");
+    expect(more).toHaveLength(0);
+    // Tag and first paragraph stay visible; the rest is collapsed.
+    expect(message).toStartWith("#a3f2b1c9 · Coder\n\nThe short answer is yes.\n\n<details>");
+    expect(message).toContain("<summary>Rest of the answer</summary>");
+    expect(message).toEndWith("</details>");
+
+    expect(formatChatRelayMessages(task, "slack", "Coder")).toEqual([
+      formatChatRelayText(task, "Coder"),
+    ]);
+    const short = { ...base, output: "fine" } as unknown as AgentTask;
+    expect(formatChatRelayMessages(short, "telegram")).toEqual(["#a3f2b1c9\n\nfine"]);
   });
 
   test("splitChatMessage keeps every chunk within the limit and loses no text", () => {
@@ -289,7 +330,7 @@ describe("chat relay watcher", () => {
       adapter: "telegram",
       threadId: `telegram:${chatId}`,
       direction: "outbound",
-      text: "observed by an extension",
+      text: `#${task.id.slice(0, 8)} · ChatRelayLead\n\nobserved by an extension`,
       taskId: task.id,
     });
   });
@@ -408,6 +449,316 @@ describe("chat relay watcher", () => {
     expect((await obligation(resume.id))?.delivered_at).not.toBeNull();
   });
 
+  test("the answer replies to the ask and starts with the task tag", async () => {
+    const chatId = nextChatId;
+    const task = await createChatTask(chatId, { askMessageId: 41 });
+    await completeTask(task.id, "Here is your answer.");
+    await processPendingChatRelays();
+
+    const [send, ...rest] = sendsTo(chatId);
+    expect(rest).toHaveLength(0);
+    expect(send?.reply_parameters).toEqual({ message_id: 41, allow_sending_without_reply: true });
+    // The line-leading tag is escaped so Telegram does not render it as a heading.
+    expect(sentText(send ?? {})).toStartWith(`\\#${task.id.slice(0, 8)} · ChatRelayLead`);
+    expect(sentText(send ?? {})).toContain("Here is your answer.");
+  });
+
+  test("the answer turns the ask's reaction into 👍, or 👎 for a failed task", async () => {
+    const reactionsTo = (chatId: number) =>
+      harness.mock.calls
+        .filter((call) => call.method === "setMessageReaction")
+        .map((call) => call.body as Record<string, unknown>)
+        .filter((body) => String(body.chat_id) === String(chatId));
+    const doneChat = nextChatId;
+    const done = await createChatTask(doneChat, { askMessageId: 51 });
+    await completeTask(done.id, "Done.");
+    const failedChat = nextChatId + 2_000;
+    const failed = await createChatTask(failedChat, { askMessageId: 52 });
+    await failTask(failed.id, "the build broke");
+    await processPendingChatRelays();
+
+    expect(reactionsTo(doneChat)).toEqual([
+      expect.objectContaining({ message_id: 51, reaction: [{ type: "emoji", emoji: "👍" }] }),
+    ]);
+    expect(reactionsTo(failedChat)).toEqual([
+      expect.objectContaining({ message_id: 52, reaction: [{ type: "emoji", emoji: "👎" }] }),
+    ]);
+  });
+
+  test("a REACTION_INVALID answer never fails the delivery", async () => {
+    const chatId = nextChatId;
+    const task = await createChatTask(chatId, { askMessageId: 61 });
+    await completeTask(task.id, "Still delivered.");
+    harness.mock.failReactions(1);
+    try {
+      await processPendingChatRelays();
+    } finally {
+      harness.mock.failReactions(0);
+    }
+    expect(sentText(sendsTo(chatId)[0] ?? {})).toContain("Still delivered.");
+    const row = await obligation(task.id);
+    expect(row?.delivered_at).not.toBeNull();
+    expect(row?.last_error).toBeNull();
+    expect(
+      harness.mock.calls.some(
+        (call) =>
+          call.method === "setMessageReaction" &&
+          String((call.body as Record<string, unknown>).chat_id) === String(chatId),
+      ),
+    ).toBe(true);
+  });
+
+  test("a chunked answer anchors only its first message", async () => {
+    const chatId = nextChatId;
+    const task = await createChatTask(chatId, { askMessageId: 42 });
+    const output = Array.from({ length: 1000 }, (_, i) => `line${String(i).padStart(4, "0")}`).join(
+      "\n",
+    );
+    await completeTask(task.id, output);
+    await processPendingChatRelays();
+
+    const sends = sendsTo(chatId);
+    expect(sends.length).toBeGreaterThan(1);
+    expect(sends[0]?.reply_parameters).toEqual({
+      message_id: 42,
+      allow_sending_without_reply: true,
+    });
+    for (const later of sends.slice(1)) expect(later.reply_parameters).toBeUndefined();
+    // Every message carries a whole collapsed block.
+    for (const body of sends) {
+      expect(sentText(body)).toContain("<details>");
+      expect(sentText(body)).toEndWith("</details>");
+      expect(sentText(body).length).toBeLessThanOrEqual(4096);
+    }
+  });
+
+  test("a deferred task posts nothing; its wake-up answers the original ask", async () => {
+    const chatId = nextChatId;
+    const deferred = await createChatTask(chatId, { askMessageId: 43 });
+    await completeTask(deferred.id, "Deferred until 18:00.", {
+      addTags: ["deferred"],
+      deferredAt: new Date().toISOString(),
+    });
+    expect(await obligation(deferred.id)).toBeNull();
+
+    // What defer-task books; the scheduler fires it later.
+    const schedule = await createScheduledTask({
+      name: `deferred-${deferred.id.slice(0, 8)}-${crypto.randomUUID()}`,
+      taskTemplate: "Check the deploy and answer.",
+      targetType: "agent-task",
+      scheduleType: "one_time",
+      nextRunAt: new Date().toISOString(),
+      targetAgentId: lead.id,
+      createdByAgentId: lead.id,
+      taskType: "deferred",
+      tags: ["deferred"],
+      parentTaskId: deferred.id,
+    });
+    const wakeUp = await createStandaloneScheduleTask(schedule);
+    expect(wakeUp.contextKey).toBe(deferred.contextKey);
+    expect(wakeUp.mentionMessageId).toBe(`${chatId}:43`);
+    await completeTask(wakeUp.id, "The deploy is live.");
+
+    await processPendingChatRelays();
+    const sends = sendsTo(chatId);
+    expect(sends).toHaveLength(1);
+    expect(sentText(sends[0] ?? {})).toContain("The deploy is live.");
+    expect(sentText(sends[0] ?? {})).not.toContain("Deferred until");
+    expect(sends[0]?.reply_parameters).toEqual({
+      message_id: 43,
+      allow_sending_without_reply: true,
+    });
+  });
+
+  test("a wake-up of a task outside chat keeps its schedule contextKey", async () => {
+    const parent = await createTaskExtended("not a chat task", { agentId: lead.id });
+    const schedule = await createScheduledTask({
+      name: `deferred-${parent.id.slice(0, 8)}-${crypto.randomUUID()}`,
+      taskTemplate: "wake up",
+      targetType: "agent-task",
+      scheduleType: "one_time",
+      nextRunAt: new Date().toISOString(),
+      targetAgentId: lead.id,
+      createdByAgentId: lead.id,
+      taskType: "deferred",
+      parentTaskId: parent.id,
+    });
+    const wakeUp = await createStandaloneScheduleTask(schedule);
+    expect(wakeUp.contextKey).toBe(`task:schedule:${schedule.id}`);
+  });
+
+  describe("a delegated worker's deferral", () => {
+    let worker: Agent;
+    let otherWorker: Agent;
+
+    beforeAll(async () => {
+      worker = await createAgent({
+        id: crypto.randomUUID(),
+        name: "ChatRelayDeferringWorker",
+        isLead: false,
+        status: "idle",
+        maxTasks: 5,
+      });
+      otherWorker = await createAgent({
+        id: crypto.randomUUID(),
+        name: "ChatRelayRetargetWorker",
+        isLead: false,
+        status: "idle",
+        maxTasks: 5,
+      });
+    });
+
+    /** A Lead chat ask (anchored on message 43) delegated to `worker`. */
+    async function delegate(
+      chatId: number,
+    ): Promise<{ leadTask: AgentTask; delegated: AgentTask }> {
+      const leadTask = await createChatTask(chatId, { askMessageId: 43 });
+      const delegated = await createTaskExtended("worker part", {
+        agentId: worker.id,
+        creatorAgentId: lead.id,
+        source: "mcp",
+        parentTaskId: leadTask.id,
+      });
+      expect(delegated.contextKey).toBe(leadTask.contextKey);
+      return { leadTask, delegated };
+    }
+
+    /** What defer-task books for `task`, fired by the scheduler. */
+    async function deferAndWake(
+      task: AgentTask,
+      options: { targetAgentId?: string } = {},
+    ): Promise<AgentTask> {
+      await completeTask(task.id, "Checking back later.", {
+        deferredAt: new Date().toISOString(),
+      });
+      const schedule = await createScheduledTask({
+        name: `deferred-${task.id.slice(0, 8)}-${crypto.randomUUID()}`,
+        taskTemplate: "resume the worker part",
+        targetType: "agent-task",
+        scheduleType: "one_time",
+        nextRunAt: new Date().toISOString(),
+        targetAgentId: options.targetAgentId ?? task.agentId ?? undefined,
+        createdByAgentId: task.agentId ?? undefined,
+        taskType: "deferred",
+        parentTaskId: task.id,
+      });
+      const wakeUp = await createStandaloneScheduleTask(schedule);
+      // The worker reports through the Lead, as its delegated task did.
+      expect(wakeUp.contextKey).toBe(`task:schedule:${schedule.id}`);
+      return wakeUp;
+    }
+
+    /**
+     * Completes the worker's `task` with raw output, then runs its Lead
+     * follow-up to a reviewed answer. Returns what reached the chat.
+     */
+    async function reportThroughLead(
+      task: AgentTask,
+      chatId: number,
+      leadTask: AgentTask,
+    ): Promise<Array<Record<string, unknown>>> {
+      const completed = await completeTask(task.id, "RAW PRIVATE WORKER RESULT");
+      expect(completed).not.toBeNull();
+      expect(await obligation(task.id)).toBeNull();
+      const followUp = await createWorkerTaskFollowUp({
+        task: completed!,
+        status: "completed",
+        output: completed!.output,
+      });
+      await processPendingChatRelays();
+      expect(sendsTo(chatId)).toHaveLength(0);
+
+      expect(followUp?.agentId).toBe(lead.id);
+      expect(followUp?.contextKey).toBe(leadTask.contextKey);
+      expect(followUp?.mentionMessageId).toBe(`${chatId}:43`);
+      await completeTask(followUp!.id, "REVIEWED LEAD ANSWER");
+      await processPendingChatRelays();
+      return sendsTo(chatId);
+    }
+
+    function expectOneReviewedAnswer(sends: Array<Record<string, unknown>>): void {
+      expect(sends).toHaveLength(1);
+      expect(sentText(sends[0] ?? {})).toContain("REVIEWED LEAD ANSWER");
+      expect(sentText(sends[0] ?? {})).not.toContain("RAW PRIVATE WORKER RESULT");
+      expect(sends[0]?.reply_parameters).toEqual({
+        message_id: 43,
+        allow_sending_without_reply: true,
+      });
+    }
+
+    test("control: an undeferred worker reports one reviewed answer", async () => {
+      const chatId = nextChatId;
+      const { leadTask, delegated } = await delegate(chatId);
+      expectOneReviewedAnswer(await reportThroughLead(delegated, chatId, leadTask));
+    });
+
+    test("wakes up outside the chat, stays silent and reports through the Lead", async () => {
+      const chatId = nextChatId;
+      const { leadTask, delegated } = await delegate(chatId);
+      const wakeUp = await deferAndWake(delegated);
+      expectOneReviewedAnswer(await reportThroughLead(wakeUp, chatId, leadTask));
+    });
+
+    test("a repeated deferral still reports through the Lead", async () => {
+      const chatId = nextChatId;
+      const { leadTask, delegated } = await delegate(chatId);
+      const firstWake = await deferAndWake(delegated);
+      const secondWake = await deferAndWake(firstWake);
+      expect(await obligation(firstWake.id)).toBeNull();
+      expectOneReviewedAnswer(await reportThroughLead(secondWake, chatId, leadTask));
+    });
+
+    test("a resume of the wake-up still reports through the Lead", async () => {
+      const chatId = nextChatId;
+      const { leadTask, delegated } = await delegate(chatId);
+      const wakeUp = await deferAndWake(delegated);
+      await startTask(wakeUp.id);
+      await supersedeTask(wakeUp.id, { reason: "graceful_shutdown", resumeTaskId: null });
+      const result = await createResumeFollowUp({
+        parentId: wakeUp.id,
+        reason: "graceful_shutdown",
+      });
+      expect(result.kind).toBe("created");
+      if (result.kind !== "created") return;
+      expect(result.task.agentId).toBe(worker.id);
+      expect(result.task.contextKey).toBe(wakeUp.contextKey);
+      expectOneReviewedAnswer(await reportThroughLead(result.task, chatId, leadTask));
+    });
+
+    test("a wake-up re-targeted to another worker reports through the Lead", async () => {
+      const chatId = nextChatId;
+      const { leadTask, delegated } = await delegate(chatId);
+      const wakeUp = await deferAndWake(delegated, { targetAgentId: otherWorker.id });
+      expect(wakeUp.agentId).toBe(otherWorker.id);
+      expectOneReviewedAnswer(await reportThroughLead(wakeUp, chatId, leadTask));
+    });
+  });
+
+  test("a deferred wake-up that runs as another agent than its parent is not relayed", async () => {
+    const other = await createAgent({
+      id: crypto.randomUUID(),
+      name: "ChatRelayOtherAgent",
+      isLead: false,
+      status: "idle",
+    });
+    const chatId = nextChatId;
+    const parent = await createChatTask(chatId);
+    await completeTask(parent.id, "Deferred.", { deferredAt: new Date().toISOString() });
+    // Bypasses the scheduler's check: the triggers hold the same line.
+    const wakeUp = await createTaskExtended("not the deferring agent", {
+      agentId: other.id,
+      source: "schedule",
+      taskType: "deferred",
+      parentTaskId: parent.id,
+      contextKey: parent.contextKey,
+    });
+    await completeTask(wakeUp.id, "OTHER AGENT OUTPUT");
+
+    expect(await obligation(wakeUp.id)).toBeNull();
+    await processPendingChatRelays();
+    expect(sendsTo(chatId)).toHaveLength(0);
+  });
+
   test("delegated worker tasks and their resumes stay silent", async () => {
     const worker = await createAgent({
       id: crypto.randomUUID(),