@desplega.ai/agent-swarm 1.173.0 → 2.0.0

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

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

@@ -0,0 +1,48 @@
+/**
+ * Per-adapter message length limits, in UTF-16 code units (what the platforms
+ * count). Outbound text longer than the limit is split into several messages.
+ */
+const CHAT_MESSAGE_LIMITS: Record<string, number> = {
+  telegram: 4096,
+  discord: 2000,
+  // Slack messages use mrkdwn, not markdown. The SDK posts our markdown as
+  // `markdown_text` (Slack converts it, 12000 character cap). 4000 is Slack's
+  // guidance for one readable message and stays well under that cap.
+  slack: 4000,
+  teams: 20000,
+};
+
+/** Used for an adapter without an entry: the smallest known limit. */
+const FALLBACK_LIMIT = 2000;
+
+export function chatMessageLimit(adapter: string): number {
+  return CHAT_MESSAGE_LIMITS[adapter] ?? FALLBACK_LIMIT;
+}
+
+/**
+ * Split `text` into chunks of at most `limit` characters. A chunk ends at the
+ * last line break inside the window, else at the last space, else at the
+ * limit. Breaks in the first half of the window are ignored, so chunks never
+ * get very short.
+ */
+export function splitChatMessage(text: string, limit: number): string[] {
+  if (limit <= 0) throw new Error("splitChatMessage: limit must be positive");
+  const chunks: string[] = [];
+  let rest = text;
+  while (rest.length > limit) {
+    const window = rest.slice(0, limit);
+    const minBreak = Math.floor(limit / 2);
+    let cut = window.lastIndexOf("\n");
+    if (cut < minBreak) cut = window.lastIndexOf(" ");
+    if (cut < minBreak) {
+      cut = limit;
+      // Never split a surrogate pair (emoji and other astral characters).
+      const code = rest.charCodeAt(cut - 1);
+      if (code >= 0xd800 && code <= 0xdbff) cut -= 1;
+    }
+    chunks.push(rest.slice(0, cut).trimEnd());
+    rest = rest.slice(cut).replace(/^[\n ]+/, "");
+  }
+  if (rest.length > 0 || chunks.length === 0) chunks.push(rest);
+  return chunks.filter((chunk, index) => chunk.length > 0 || index === 0);
+}

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

@@ -0,0 +1,81 @@
+import type { Logger } from "chat";
+import { scrubObject, scrubSecrets } from "@/utils/secret-scrubber";
+
+/** Called for every warn/error line, already scrubbed. Feeds adapter health. */
+export type ChatLogIssueSink = (level: "warn" | "error", message: string) => void;
+
+/** Bound on the issue text handed to the sink (adapter health `lastWarning`). */
+const MAX_ISSUE_CHARS = 300;
+
+function scrubArg(arg: unknown): unknown {
+  if (arg instanceof Error) return scrubSecrets(`${arg.name}: ${arg.message}`);
+  return scrubObject(arg);
+}
+
+function describeCause(value: unknown): string {
+  return value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+}
+
+/**
+ * The cause of a warn/error line: an `Error` argument, or the `error` / `err`
+ * field of an object argument (adapters log `{ error: String(error) }`).
+ */
+function causeOf(args: unknown[]): string | undefined {
+  for (const arg of args) {
+    if (arg instanceof Error) return describeCause(arg);
+    if (arg && typeof arg === "object") {
+      const record = arg as Record<string, unknown>;
+      const value = record.error ?? record.err;
+      if (value !== undefined && value !== null) return describeCause(value);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * SDK `Logger` that scrubs every argument before it reaches the console. The
+ * Chat SDK has no egress hook like `installSlackEgressScrub`, so the logger is
+ * the scrub point for everything the SDK and its adapters print.
+ */
+export function createScrubbingLogger(prefix: string, onIssue?: ChatLogIssueSink): Logger {
+  const tag = `[chat-sdk:${prefix}]`;
+  const emit = (level: "info" | "warn" | "error", message: string, args: unknown[]): void => {
+    const scrubbedMessage = scrubSecrets(message);
+    const scrubbedArgs = args.map(scrubArg);
+    if (onIssue && (level === "warn" || level === "error")) {
+      const cause = causeOf(args);
+      const issue = cause ? `${scrubbedMessage}: ${scrubSecrets(cause)}` : scrubbedMessage;
+      onIssue(level, issue.slice(0, MAX_ISSUE_CHARS));
+    }
+    console[level](tag, scrubbedMessage, ...scrubbedArgs);
+  };
+  return {
+    // Debug is dropped, matching the SDK's default ConsoleLogger("info") level.
+    debug: () => {},
+    info: (message, ...args) => emit("info", message, args),
+    warn: (message, ...args) => emit("warn", message, args),
+    error: (message, ...args) => emit("error", message, args),
+    child: (childPrefix) => createScrubbingLogger(`${prefix}:${childPrefix}`, onIssue),
+  };
+}
+
+/**
+ * Drop `info` lines for which `keep(message)` is false. Warn and error lines
+ * always pass. Child loggers keep the filter.
+ */
+export function withInfoFilter(logger: Logger, keep: (message: string) => boolean): Logger {
+  return {
+    debug: (message, ...args) => logger.debug(message, ...args),
+    info: (message, ...args) => {
+      if (keep(message)) logger.info(message, ...args);
+    },
+    warn: (message, ...args) => logger.warn(message, ...args),
+    error: (message, ...args) => logger.error(message, ...args),
+    child: (childPrefix) => withInfoFilter(logger.child(childPrefix), keep),
+  };
+}
+
+/** Error text for logs and tool results, scrubbed. */
+export function errorMessage(err: unknown): string {
+  return scrubSecrets(err instanceof Error ? err.message : String(err));
+}

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

@@ -0,0 +1,123 @@
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { workflowEventBus } from "@/workflows/event-bus";
+import { chatMessageLimit, splitChatMessage } from "./limits";
+import { getChatInstance } from "./runtime";
+import { assertTrustedChatTarget } from "./teams-origin";
+
+/** The adapter is not configured, failed to start, or is shutting down. */
+export class ChatAdapterUnavailableError extends Error {
+  constructor(adapter: string) {
+    super(`Chat SDK adapter '${adapter}' is not running`);
+    this.name = "ChatAdapterUnavailableError";
+  }
+}
+
+export interface ChatSentEvent {
+  adapter: string;
+  channelId: string;
+  threadId: string;
+  text: string;
+  taskId?: string;
+  messageId?: string;
+}
+
+/**
+ * Publish an outbound message on the bus. The post-bridge turns it into the
+ * `post.chat.message` extension event with `direction: "outbound"`.
+ */
+export function emitChatMessageSent(event: ChatSentEvent): void {
+  workflowEventBus.emit("chat.message.sent", { ...event, text: scrubSecrets(event.text) });
+}
+
+/** The adapter name is the first segment of an SDK thread or channel id. */
+export function adapterOfChatId(id: string): string {
+  const index = id.indexOf(":");
+  return index === -1 ? id : id.slice(0, index);
+}
+
+export interface ChatPostResult {
+  adapter: string;
+  threadId: string;
+  channelId: string;
+  /** One id per chunk, in send order. */
+  messageIds: string[];
+}
+
+interface PostTarget {
+  post(message: { markdown: string }): Promise<{ id: string; threadId?: string }>;
+}
+
+async function postChunks(
+  adapter: string,
+  target: PostTarget,
+  text: string,
+): Promise<{ messageIds: string[]; threadId?: string }> {
+  const messageIds: string[] = [];
+  let threadId: string | undefined;
+  for (const chunk of splitChatMessage(text, chatMessageLimit(adapter))) {
+    const sent = await target.post({ markdown: chunk });
+    messageIds.push(sent.id);
+    threadId ??= sent.threadId;
+  }
+  return { messageIds, threadId };
+}
+
+/**
+ * Post markdown to a Chat SDK thread or channel. Scrubs the text, splits it by
+ * the adapter limit, and emits one `chat.message.sent` for the whole message
+ * once every chunk was accepted. Throws `ChatAdapterUnavailableError` when the
+ * adapter is not running, `UntrustedTeamsServiceUrlError` before any send
+ * when a Teams id points at a host that is not Bot Framework, and the adapter
+ * error when a send fails.
+ *
+ * Delivery is at-least-once: a chunk failure re-posts earlier chunks on retry,
+ * and a crash between the send and `markChatRelayDelivered` re-sends the
+ * message.
+ */
+export async function postChatMessage(args: {
+  adapter: string;
+  threadId?: string;
+  channelId?: string;
+  text: string;
+  taskId?: string;
+}): Promise<ChatPostResult> {
+  // Ids come from tools and stored context keys. Check the Teams origin
+  // before the adapter sends its token.
+  assertTrustedChatTarget(args.threadId ?? args.channelId ?? "");
+  const chat = getChatInstance(args.adapter);
+  if (!chat) throw new ChatAdapterUnavailableError(args.adapter);
+  const text = scrubSecrets(args.text);
+
+  let result: ChatPostResult;
+  if (args.threadId) {
+    const thread = chat.thread(args.threadId);
+    const sent = await postChunks(args.adapter, thread, text);
+    result = {
+      adapter: args.adapter,
+      threadId: thread.id,
+      channelId: thread.channelId,
+      messageIds: sent.messageIds,
+    };
+  } else if (args.channelId) {
+    const channel = chat.channel(args.channelId);
+    const sent = await postChunks(args.adapter, channel, text);
+    result = {
+      adapter: args.adapter,
+      threadId: sent.threadId ?? channel.id,
+      channelId: channel.id,
+      messageIds: sent.messageIds,
+    };
+  } else {
+    throw new Error("postChatMessage needs a threadId or a channelId");
+  }
+
+  emitChatMessageSent({
+    adapter: result.adapter,
+    channelId: result.channelId,
+    threadId: result.threadId,
+    text,
+    taskId: args.taskId,
+    messageId: result.messageIds.at(-1),
+  });
+  return result;
+}