@desplega.ai/agent-swarm 1.172.0 → 2.0.0

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

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

@@ -0,0 +1,172 @@
+import {
+  getPendingChatRelayTasks,
+  giveUpStaleChatRelays,
+  markChatRelayAttempted,
+  markChatRelayDelivered,
+  markChatRelayGivenUp,
+  recordChatRelayError,
+} from "@/be/db";
+import { chatThreadOfContextKey } from "@/tasks/context-key";
+import type { AgentTask } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { workflowEventBus } from "@/workflows/event-bus";
+import { errorMessage } from "./logger";
+import { postChatMessage } from "./outbound";
+import { getChatInstance, getChatSdkHealth } from "./runtime";
+import { sweepExpired } from "./state";
+import { stopTypingKeepalive } from "./typing";
+
+/**
+ * Stop retrying a relay row this long after its obligation was created. Time,
+ * not attempts: with exponential backoff a short platform outage would
+ * otherwise burn a fixed attempt budget in minutes.
+ */
+export const RELAY_GIVE_UP_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Run `sweepExpired` on every Nth tick, including event-triggered ticks (so
+ * about once a minute when only the 3 s interval ticks).
+ */
+const SWEEP_EVERY_N_TICKS = 20;
+
+/** Coalesce bursts of terminal-task events into one early tick. */
+const EARLY_TICK_DEBOUNCE_MS = 250;
+
+/** The text posted for a terminal task. Failed and cancelled tasks get a status line first. */
+export function formatChatRelayText(task: AgentTask): string {
+  const body = (task.output || task.failureReason || "").trim();
+  if (task.status === "failed") return body ? `**Task failed.**\n\n${body}` : "**Task failed.**";
+  if (task.status === "cancelled") {
+    return body ? `**Task cancelled.**\n\n${body}` : "**Task cancelled.**";
+  }
+  return body || "Task completed.";
+}
+
+/**
+ * Deliver every pending, out-of-backoff chat relay row for a running adapter.
+ * Exported with an injectable clock so retry and give-up behavior is testable
+ * without waiting.
+ *
+ * Delivery is at-least-once: a chunk failure re-posts the earlier chunks on
+ * retry, and a crash between the send and `markChatRelayDelivered` re-sends the
+ * message.
+ *
+ * Once `signal` aborts, no further row is claimed. A send already in flight is
+ * not cancelled (`postChatMessage` takes no signal); its row keeps the claim
+ * and retries after the normal backoff.
+ */
+export async function processPendingChatRelays(
+  now: number = Date.now(),
+  signal?: AbortSignal,
+): Promise<void> {
+  // Rows older than the give-up age are retired first, so rows of a stopped
+  // adapter do not stay pending forever.
+  const retired = await giveUpStaleChatRelays(now, RELAY_GIVE_UP_AFTER_MS);
+  if (retired > 0) console.warn(`[chat-sdk] Gave up relaying ${retired} stale task(s)`);
+
+  const running = Object.entries(getChatSdkHealth())
+    .filter(([, adapterHealth]) => adapterHealth?.status === "ok")
+    .map(([name]) => name);
+
+  for (const pending of await getPendingChatRelayTasks(now, 200, running)) {
+    if (signal?.aborted) return;
+    const { task } = pending;
+    const target = chatThreadOfContextKey(task.contextKey);
+    // `created_at` is ISO text with a `Z` suffix (migration 217 default).
+    const createdAtMs = Date.parse(pending.createdAt);
+
+    if (Number.isFinite(createdAtMs) && now - createdAtMs >= RELAY_GIVE_UP_AFTER_MS) {
+      const reason = pending.lastError ?? "no successful delivery within 24 hours";
+      if (await markChatRelayGivenUp(task.id, reason, now)) {
+        console.warn(scrubSecrets(`[chat-sdk] Gave up relaying task ${task.id}: ${reason}`));
+      }
+      if (target) stopTypingKeepalive(target.threadId);
+      continue;
+    }
+    if (!target) {
+      // The trigger only enqueues chat-sdk keys; a key that no longer parses
+      // can never be delivered.
+      await markChatRelayGivenUp(task.id, "task has no chat-sdk contextKey", now);
+      continue;
+    }
+    // Stopping adapter: skip without counting an attempt.
+    if (!getChatInstance(target.adapter)) continue;
+
+    if (!(await markChatRelayAttempted(task.id, now))) continue;
+    try {
+      await postChatMessage({
+        adapter: target.adapter,
+        threadId: target.threadId,
+        text: formatChatRelayText(task),
+        taskId: task.id,
+      });
+      stopTypingKeepalive(target.threadId);
+      await markChatRelayDelivered(task.id, now);
+      console.log(`[chat-sdk] Relayed ${task.status} task ${task.id} to ${target.adapter}`);
+    } catch (error) {
+      const message = errorMessage(error);
+      await recordChatRelayError(task.id, message, now);
+      console.error(`[chat-sdk] Relay of task ${task.id} failed: ${message}`);
+    }
+  }
+}
+
+let interval: ReturnType<typeof setInterval> | undefined;
+let earlyTick: ReturnType<typeof setTimeout> | undefined;
+let processing: Promise<void> | undefined;
+let stopController: AbortController | undefined;
+let tickCount = 0;
+
+async function tick(): Promise<void> {
+  if (processing) return;
+  tickCount += 1;
+  const now = Date.now();
+  processing = (async () => {
+    try {
+      await processPendingChatRelays(now, stopController?.signal);
+      if (tickCount % SWEEP_EVERY_N_TICKS === 0) await sweepExpired(now);
+    } catch (error) {
+      console.error(`[chat-sdk] Relay tick failed: ${errorMessage(error)}`);
+    }
+  })();
+  try {
+    await processing;
+  } finally {
+    processing = undefined;
+  }
+}
+
+function scheduleEarlyTick(): void {
+  if (!interval || earlyTick) return;
+  earlyTick = setTimeout(() => {
+    earlyTick = undefined;
+    void tick();
+  }, EARLY_TICK_DEBOUNCE_MS);
+}
+
+const TERMINAL_EVENTS = ["task.completed", "task.failed", "task.cancelled"] as const;
+
+/** Start the relay watcher. Idempotent. A terminal task event triggers an early tick. */
+export function startChatRelayWatcher(intervalMs = 3000): void {
+  if (interval) return;
+  tickCount = 0;
+  stopController = new AbortController();
+  interval = setInterval(() => void tick(), intervalMs);
+  for (const event of TERMINAL_EVENTS) workflowEventBus.on(event, scheduleEarlyTick);
+  void tick();
+}
+
+/**
+ * Stop the watcher: no new tick, no new claim. The returned promise settles
+ * when an in-flight tick finishes, which an unanswered platform call can delay
+ * without bound, so shutdown waits for it under its own deadline.
+ */
+export async function stopChatRelayWatcher(): Promise<void> {
+  stopController?.abort();
+  if (interval) clearInterval(interval);
+  interval = undefined;
+  if (earlyTick) clearTimeout(earlyTick);
+  earlyTick = undefined;
+  for (const event of TERMINAL_EVENTS) workflowEventBus.off(event, scheduleEarlyTick);
+  if (processing) await processing;
+}

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

@@ -0,0 +1,169 @@
+import {
+  deleteKv,
+  getAgentById,
+  getAgentWorkingOnContextKey,
+  getAllAgents,
+  getKv,
+  getLeadAgent,
+  upsertKv,
+} from "@/be/db";
+import { isAgentReachable } from "@/be/runtime-pools/reachability";
+import { chatSdkContextKey } from "@/tasks/context-key";
+import type { Agent, RoutingReason } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+
+/** KV namespace of the channel-to-agent/workflow mapping, written by `register-chat-channel`. */
+export const CHAT_CHANNELS_NAMESPACE = "integrations:chat:channels";
+
+export interface ChatChannelMapping {
+  agentId?: string;
+  workflowId?: string;
+  name?: string;
+  createdAt?: string;
+}
+
+export interface ChatAgentMatch {
+  /** Null when no lead exists: the task is created unassigned and queued. */
+  agent: Agent | null;
+  reason: RoutingReason;
+  matchedText: string;
+}
+
+export type ChatRouteTarget =
+  | { kind: "agents"; matches: ChatAgentMatch[] }
+  | { kind: "workflow"; workflowId: string };
+
+export interface ChatRouteContext {
+  adapter: string;
+  channelId: string;
+  threadId: string;
+  botMentioned: boolean;
+  isDirectMessage: boolean;
+}
+
+/**
+ * KV key of a channel mapping. SDK channel ids already carry the adapter
+ * prefix (`telegram:555001`, `slack:C123`); the prefix is added only when an
+ * adapter returns a bare id, so the key is always `<adapter>:<platform id>`.
+ */
+export function chatChannelKey(adapter: string, channelId: string): string {
+  return channelId.startsWith(`${adapter}:`) ? channelId : `${adapter}:${channelId}`;
+}
+
+export async function getChatChannelMapping(
+  adapter: string,
+  channelId: string,
+): Promise<ChatChannelMapping | null> {
+  const row = await getKv(CHAT_CHANNELS_NAMESPACE, chatChannelKey(adapter, channelId));
+  if (!row || typeof row.value !== "object" || row.value === null) return null;
+  return row.value as ChatChannelMapping;
+}
+
+/** Store a channel mapping under `chatChannelKey(adapter, channelId)`. Returns the key. */
+export async function putChatChannelMapping(
+  adapter: string,
+  channelId: string,
+  mapping: ChatChannelMapping,
+): Promise<string> {
+  const key = chatChannelKey(adapter, channelId);
+  await upsertKv({
+    namespace: CHAT_CHANNELS_NAMESPACE,
+    key,
+    value: mapping,
+    valueType: "json",
+    expiresAt: null,
+  });
+  return key;
+}
+
+export async function deleteChatChannelMapping(
+  adapter: string,
+  channelId: string,
+): Promise<boolean> {
+  return deleteKv(CHAT_CHANNELS_NAMESPACE, chatChannelKey(adapter, channelId));
+}
+
+/** Remove `swarm#<uuid>` and `swarm#all` routing tokens from task text. */
+export function stripRoutingTokens(text: string): string {
+  return text
+    .replace(/swarm#[a-f0-9-]{36}/gi, "")
+    .replace(/swarm#all/gi, "")
+    .trim();
+}
+
+async function leadMatch(reachable: Agent[], matchedText: string): Promise<ChatAgentMatch> {
+  const lead = reachable.find((agent) => agent.isLead) ?? (await getLeadAgent());
+  return { agent: lead, reason: "skill", matchedText };
+}
+
+/**
+ * Port of `src/slack/router.ts` for Chat SDK threads. Order: `swarm#<uuid>`,
+ * `swarm#all`, KV channel mapping (agent, or workflow for a mention or DM), the
+ * thread owner (lead when the owner is offline), the lead for a mention or DM.
+ * Returns null when the message is not addressed to the swarm.
+ */
+export async function routeChatMessage(
+  text: string,
+  ctx: ChatRouteContext,
+): Promise<ChatRouteTarget | null> {
+  const allAgents = await getAllAgents();
+  const reachableFlags = await Promise.all(allAgents.map((agent) => isAgentReachable(agent)));
+  const reachable = allAgents.filter((_, index) => reachableFlags[index]);
+
+  const matches: ChatAgentMatch[] = [];
+  for (const match of text.matchAll(/swarm#([a-f0-9-]{36})/gi)) {
+    const agentId = match[1];
+    if (!agentId || matches.some((m) => m.agent?.id === agentId)) continue;
+    const agent = await getAgentById(agentId);
+    if (agent && (await isAgentReachable(agent))) {
+      matches.push({ agent, reason: "human_pinned", matchedText: match[0] });
+    }
+  }
+  if (/swarm#all/i.test(text)) {
+    for (const agent of reachable) {
+      if (agent.isLead || matches.some((m) => m.agent?.id === agent.id)) continue;
+      matches.push({ agent, reason: "human_pinned", matchedText: "swarm#all" });
+    }
+  }
+  if (matches.length > 0) return { kind: "agents", matches };
+
+  const mapping = await getChatChannelMapping(ctx.adapter, ctx.channelId);
+  // A workflow run has no continuity: an unaddressed reply in the subscribed
+  // thread must not start another run. It still reaches a thread owner below.
+  if (mapping?.workflowId && (ctx.botMentioned || ctx.isDirectMessage)) {
+    return { kind: "workflow", workflowId: mapping.workflowId };
+  }
+  if (mapping?.agentId) {
+    const agent = await getAgentById(mapping.agentId);
+    if (agent) {
+      return {
+        kind: "agents",
+        matches: [{ agent, reason: "human_pinned", matchedText: "channel mapping" }],
+      };
+    }
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] Channel mapping for ${ctx.channelId} names unknown agent ${mapping.agentId}; using the default route`,
+      ),
+    );
+  }
+
+  const owner = await getAgentWorkingOnContextKey(chatSdkContextKey(ctx.threadId), "chat");
+  if (owner && (await isAgentReachable(owner))) {
+    return {
+      kind: "agents",
+      matches: [{ agent: owner, reason: "continuity", matchedText: "thread follow-up" }],
+    };
+  }
+  if (owner) {
+    return {
+      kind: "agents",
+      matches: [await leadMatch(reachable, "thread follow-up (lead fallback)")],
+    };
+  }
+
+  if (ctx.botMentioned || ctx.isDirectMessage) {
+    return { kind: "agents", matches: [await leadMatch(reachable, "@bot")] };
+  }
+  return null;
+}