@desplega.ai/agent-swarm 1.172.0 → 2.0.0

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

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

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

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

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

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

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

@@ -0,0 +1,426 @@
+import type { Adapter, Message, Thread } from "chat";
+import { z } from "zod";
+import {
+  getAgentById,
+  getAllAgents,
+  getLatestActiveTaskByContextKey,
+  getLatestTaskByContextKey,
+  getLeadAgent,
+  isExtensionAgent,
+} from "@/be/db";
+import { dispatchPre } from "@/extensions/dispatcher";
+import { resolveTemplate } from "@/prompts/resolver";
+import { chatSdkContextKey } from "@/tasks/context-key";
+import { TaskCreationBlockedError } from "@/tasks/errors";
+import type { CreateTaskOptions } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { getExecutorRegistry } from "@/workflows";
+import { workflowEventBus } from "@/workflows/event-bus";
+import { handleWebhookTrigger } from "@/workflows/triggers";
+import {
+  buildChatAttachmentText,
+  createChatTaskWithFiles,
+  fetchChatFiles,
+  toChatFiles,
+} from "./attachments";
+import { getChatThreadResetAt } from "./commands";
+import { errorMessage } from "./logger";
+import { emitChatMessageSent } from "./outbound";
+import {
+  type ChatAgentMatch,
+  type ChatRouteTarget,
+  routeChatMessage,
+  stripRoutingTokens,
+} from "./router";
+import { getChatInstance } from "./runtime";
+import { readPersistedThreadHistory } from "./state";
+import { formatChatSteeringAck, requestChatThreadSteering } from "./steering";
+import {
+  bufferChatMessage,
+  type ChatBufferedMessage,
+  instantFlushChat,
+  isChatThreadBuffered,
+} from "./thread-buffer";
+import { startTypingKeepalive, stopTypingKeepalive } from "./typing";
+// Side-effect import: registers the Chat SDK prompt templates.
+import "./templates";
+
+export type ChatInboundKind = "mention" | "dm" | "subscribed";
+
+/** Runtime check for `pre.chat.route` modifications (mirrors `ChatRouteModify`). */
+export const ChatRouteModifySchema = z
+  .object({
+    target: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("agent"), agentId: z.string().min(1) }).strict(),
+      z.object({ kind: z.literal("lead") }).strict(),
+      z.object({ kind: z.literal("broadcast") }).strict(),
+      z.object({ kind: z.literal("workflow"), workflowId: z.string().min(1) }).strict(),
+    ]),
+  })
+  .strict();
+
+const THREAD_CONTEXT_LIMIT = 20;
+const AGENT_MESSAGE_TRUNCATE = 500;
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Remove the bot's own `@name` / `<@id>` mention; other mentions stay. */
+function stripBotMention(text: string, adapter: Adapter): string {
+  let out = text;
+  if (adapter.userName) {
+    out = out.replace(new RegExp(`(?<!\\w)@${escapeRegex(adapter.userName)}(?![\\w-])`, "gi"), "");
+  }
+  if (adapter.botUserId) {
+    out = out.replace(new RegExp(`<@${escapeRegex(adapter.botUserId)}>`, "g"), "");
+  }
+  return out.trim();
+}
+
+/** The adapter name is the thread id's first segment; the rest of the id is opaque. */
+function adapterOf(threadId: string): string {
+  const i = threadId.indexOf(":");
+  return i === -1 ? threadId : threadId.slice(0, i);
+}
+
+/**
+ * Entry point for every human message the SDK hands to the swarm. Steering is
+ * tried whatever the handler kind: the SDK routes a DM to `onDirectMessage`
+ * even when its thread is subscribed. Everything else goes through the buffer.
+ */
+export async function handleChatInbound(
+  thread: Thread,
+  message: Message,
+  kind: ChatInboundKind,
+): Promise<void> {
+  const adapter = thread.adapter.name;
+  workflowEventBus.emit("chat.message.received", {
+    adapter,
+    channelId: thread.channelId,
+    threadId: thread.id,
+    userId: message.author.userId,
+    text: message.text,
+    messageId: message.id,
+  });
+
+  let text = stripBotMention(message.text ?? "", thread.adapter);
+  const immediate = /^!now\b/i.test(text);
+  if (immediate) text = text.replace(/^!now\s*/i, "").trim();
+  const attachments = message.attachments ?? [];
+
+  // A thread with messages already waiting keeps its order: append, do not steer past them.
+  if (!immediate && attachments.length === 0 && text && !isChatThreadBuffered(thread.id)) {
+    const steering = await requestChatThreadSteering({
+      contextKey: chatSdkContextKey(thread.id),
+      message: text,
+    });
+    if (steering) {
+      console.log(
+        `[chat-sdk] ${adapter} message steered task ${steering.task.id} (${steering.result.outcome})`,
+      );
+      try {
+        const ack = formatChatSteeringAck(steering.result);
+        const sent = await thread.post({ markdown: ack });
+        emitChatMessageSent({
+          adapter,
+          channelId: thread.channelId,
+          threadId: thread.id,
+          text: ack,
+          taskId: steering.task.id,
+          messageId: sent.id,
+        });
+        // The acknowledgement is the reply to this message.
+        stopTypingKeepalive(thread.id);
+      } catch (error) {
+        console.warn(
+          `[chat-sdk] Could not post the steering acknowledgement: ${errorMessage(error)}`,
+        );
+      }
+      return;
+    }
+  }
+
+  if (text || attachments.length > 0) {
+    bufferChatMessage(thread.id, {
+      messageId: message.id,
+      channelId: thread.channelId,
+      text,
+      userId: message.author.userId,
+      userName: message.author.userName || undefined,
+      botMentioned: kind === "mention" || message.isMention === true,
+      isDirectMessage: kind === "dm" || thread.isDM,
+      attachments,
+    });
+    // Subscribed-thread messages may be dropped by the router at flush time;
+    // they get typing once a task exists (see flushChatThread).
+    if (kind !== "subscribed") startTypingKeepalive(adapter, thread.id);
+  }
+  if (immediate) await instantFlushChat(thread.id);
+}
+
+/**
+ * Earlier messages of the thread for the task description, minus the flushed
+ * ones and anything before the last `/reset`. The adapter's view is merged with
+ * the history the SDK persisted: Telegram answers from process memory, which an
+ * adapter restart (API restart, config reload) empties.
+ */
+async function getChatThreadContext(
+  thread: Thread,
+  exclude: ReadonlySet<string>,
+  since: Date | null,
+): Promise<string> {
+  try {
+    await thread.refresh();
+    const byId = new Map<string, Message>();
+    for (const m of await readPersistedThreadHistory(thread.id)) byId.set(m.id, m);
+    for (const m of thread.recentMessages) byId.set(m.id, m);
+    return [...byId.values()]
+      .sort((a, b) => a.metadata.dateSent.getTime() - b.metadata.dateSent.getTime())
+      .filter((m) => !exclude.has(m.id) && m.text.trim() !== "")
+      .filter((m) => since === null || m.metadata.dateSent.getTime() > since.getTime())
+      .slice(-THREAD_CONTEXT_LIMIT)
+      .map((m) => {
+        if (m.author.isMe || m.author.isBot === true) {
+          const truncated =
+            m.text.length > AGENT_MESSAGE_TRUNCATE
+              ? `${m.text.slice(0, AGENT_MESSAGE_TRUNCATE)}...`
+              : m.text;
+          return `[Agent]: ${truncated}`;
+        }
+        return `${m.author.userName || m.author.fullName || m.author.userId}: ${m.text}`;
+      })
+      .join("\n");
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not read thread context: ${errorMessage(error)}`);
+    return "";
+  }
+}
+
+/** Apply a `pre.chat.route` modification, or null to fall back to the built-in router. */
+async function targetFromExtension(
+  target: z.infer<typeof ChatRouteModifySchema>["target"],
+): Promise<ChatRouteTarget | null> {
+  switch (target.kind) {
+    case "workflow":
+      return { kind: "workflow", workflowId: target.workflowId };
+    case "broadcast": {
+      const matches = (await getAllAgents())
+        .filter((agent) => !agent.isLead)
+        .map(
+          (agent): ChatAgentMatch => ({ agent, reason: "human_pinned", matchedText: "extension" }),
+        );
+      if (matches.length === 0) {
+        console.warn("[chat-sdk] Extension broadcast target matched no agents; message dropped");
+      }
+      return { kind: "agents", matches };
+    }
+    case "lead": {
+      const lead = await getLeadAgent();
+      if (lead) {
+        return {
+          kind: "agents",
+          matches: [{ agent: lead, reason: "human_pinned", matchedText: "extension" }],
+        };
+      }
+      console.warn("[chat-sdk] Extension selected the lead, but no lead exists. Using the router.");
+      return null;
+    }
+    case "agent": {
+      const agent = await getAgentById(target.agentId);
+      if (agent && !isExtensionAgent(agent)) {
+        return {
+          kind: "agents",
+          matches: [{ agent, reason: "human_pinned", matchedText: "extension" }],
+        };
+      }
+      console.warn(
+        scrubSecrets(
+          `[chat-sdk] Extension selected ${agent ? "an extension-identity" : "an unknown"} agent ${target.agentId}. Using the router.`,
+        ),
+      );
+      return null;
+    }
+  }
+}
+
+/**
+ * Buffer flush: one routed decision for every message the thread collected.
+ * Runs outside any transaction, so `pre.chat.route` is dispatched here, after
+ * the flush and before any task exists.
+ */
+export async function flushChatThread(
+  threadId: string,
+  items: ChatBufferedMessage[],
+  immediate: boolean,
+): Promise<void> {
+  const first = items[0];
+  if (!first) return;
+  const adapter = adapterOf(threadId);
+  const contextKey = chatSdkContextKey(threadId);
+  const thread = getChatInstance(adapter)?.thread(threadId);
+  const rawText = items
+    .map((item) => item.text)
+    .filter(Boolean)
+    .join("\n---\n");
+  const botMentioned = items.some((item) => item.botMentioned);
+  const isDirectMessage = items.some((item) => item.isDirectMessage);
+
+  // After `/reset` the thread's earlier tasks are not context: the new task gets
+  // no parent and no thread history older than the reset.
+  const resetAt = await getChatThreadResetAt(threadId);
+  const previousTask = await getLatestTaskByContextKey(contextKey);
+  const mostRecentTask =
+    previousTask && resetAt && new Date(previousTask.createdAt).getTime() <= resetAt.getTime()
+      ? null
+      : previousTask;
+  const routeResult = await dispatchPre(
+    "pre.chat.route",
+    {
+      adapter,
+      channelId: first.channelId,
+      threadId,
+      userId: first.userId,
+      ...(first.userName ? { userName: first.userName } : {}),
+      text: rawText,
+      botMentioned,
+      isDirectMessage,
+      ...(mostRecentTask ? { threadContext: { adapter, threadId } } : {}),
+    },
+    {
+      // A runtime-invalid target is an extension failure, not a routing input.
+      validateModify: (data) => {
+        const parsed = ChatRouteModifySchema.safeParse(data);
+        return parsed.success
+          ? { success: true, data: parsed.data }
+          : { success: false, error: new Error(parsed.error.message) };
+      },
+    },
+  );
+  if (routeResult.action === "block") {
+    console.info(
+      `[chat-sdk] Extension blocked routing for ${threadId}:`,
+      scrubSecrets(routeResult.reason),
+    );
+    stopTypingKeepalive(threadId);
+    return;
+  }
+
+  let target: ChatRouteTarget | null = null;
+  if (routeResult.action === "modify") target = await targetFromExtension(routeResult.data.target);
+  target ??= await routeChatMessage(rawText, {
+    adapter,
+    channelId: first.channelId,
+    threadId,
+    botMentioned,
+    isDirectMessage,
+  });
+  if (!target) {
+    console.log(`[chat-sdk] ${threadId}: message not addressed to the swarm, ignored`);
+    stopTypingKeepalive(threadId);
+    return;
+  }
+
+  if (target.kind === "workflow") {
+    // A workflow run has no relay that would stop the indicator.
+    stopTypingKeepalive(threadId);
+    try {
+      // The adapter verified the platform signature, and the workflow id comes
+      // from an operator mapping or an extension, never from the message.
+      const { runId } = await handleWebhookTrigger(
+        target.workflowId,
+        {
+          adapter,
+          channelId: first.channelId,
+          threadId,
+          contextKey,
+          userId: first.userId,
+          userName: first.userName,
+          text: rawText,
+          messageIds: items.map((item) => item.messageId),
+        },
+        {},
+        getExecutorRegistry(),
+        { alreadyAuthenticated: true },
+      );
+      console.log(`[chat-sdk] ${threadId}: started workflow run ${runId}`);
+      await subscribe(thread);
+    } catch (error) {
+      console.error(`[chat-sdk] ${threadId}: workflow dispatch failed: ${errorMessage(error)}`);
+    }
+    return;
+  }
+
+  const body = stripRoutingTokens(rawText);
+  const files = items.flatMap((item) => toChatFiles(adapter, item.messageId, item.attachments));
+  await using inbound = await fetchChatFiles(files);
+  const fileText = buildChatAttachmentText(inbound.files, inbound.failed);
+  const combined = [body, fileText].filter(Boolean).join("\n\n");
+  const marked =
+    items.length > 1
+      ? `[Thread follow-up: ${items.length} message(s) buffered]\n\n${combined}`
+      : combined;
+  const threadContext =
+    mostRecentTask && thread
+      ? await getChatThreadContext(thread, new Set(items.map((item) => item.messageId)), resetAt)
+      : "";
+  const description = threadContext
+    ? `${resolveTemplate("chat.message.thread_context", { thread_messages: threadContext }).text}\n\n${marked}`
+    : marked;
+
+  const latestActive = await getLatestActiveTaskByContextKey(contextKey, "chat");
+  const dependsOn = !immediate && latestActive ? [latestActive.id] : undefined;
+  let created = 0;
+  for (const match of target.matches) {
+    const options: CreateTaskOptions = {
+      agentId: match.agent?.id ?? null,
+      routingReason: match.agent ? match.reason : undefined,
+      routingSource: match.agent ? "engine_default" : undefined,
+      source: "chat",
+      taskType: "chat-inbound",
+      tags: ["chat-sdk", adapter],
+      priority: 70,
+      contextKey,
+      dependsOn,
+      parentTaskId: mostRecentTask?.id,
+      // A human message in the thread: never answer it in the previous task's
+      // structured-output contract.
+      inheritParentOutputSchema: false,
+    };
+    try {
+      const { task, unattached } = await createChatTaskWithFiles(description, options, inbound);
+      created++;
+      console.log(
+        `[chat-sdk] ${threadId}: task ${task.id} for ${match.agent ? `agent ${match.agent.id}` : "no agent (queued)"} (${match.matchedText}, dependsOn: ${dependsOn?.join(", ") ?? "none"}${unattached.length ? `, ${unattached.length} file(s) not attached` : ""})`,
+      );
+    } catch (error) {
+      if (error instanceof TaskCreationBlockedError) {
+        console.info(
+          `[chat-sdk] ${threadId}: task creation blocked: ${scrubSecrets(error.reason)}`,
+        );
+      } else {
+        console.error(`[chat-sdk] ${threadId}: task creation failed: ${errorMessage(error)}`);
+      }
+    }
+  }
+  if (created > 0) {
+    await subscribe(thread);
+    // Subscribed-thread messages start typing only here, once a task exists.
+    startTypingKeepalive(adapter, threadId);
+  } else {
+    stopTypingKeepalive(threadId);
+  }
+}
+
+/**
+ * Subscribe so plain replies reach `onSubscribedMessage`. Threads stay
+ * subscribed after a terminal task: a later reply is a follow-up.
+ */
+async function subscribe(thread: Thread | undefined): Promise<void> {
+  if (!thread) return;
+  try {
+    if (!(await thread.isSubscribed())) await thread.subscribe();
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not subscribe to ${thread.id}: ${errorMessage(error)}`);
+  }
+}