@desplega.ai/agent-swarm 2.4.4 → 2.5.0

package/src/http/webhooks.ts

@@ -31,6 +31,17 @@ import {
   isAzureDevOpsEnabled,
   verifyAzureDevOpsWebhook,
 } from "../azure-devops";
+import {
+  pullRequestCommentEventOf as bitbucketCommentEventOf,
+  pullRequestEventOf as bitbucketPullRequestEventOf,
+  handlePullRequestClosed as handleBitbucketPullRequestClosed,
+  handlePullRequestCommentCreated as handleBitbucketPullRequestCommentCreated,
+  handlePullRequestCreated as handleBitbucketPullRequestCreated,
+  isBitbucketEnabled,
+  isDuplicateDelivery as isDuplicateBitbucketDelivery,
+  markDeliveryProcessed as markBitbucketDeliveryProcessed,
+  verifyBitbucketWebhook,
+} from "../bitbucket";
 import type {
   CheckRunEvent,
   CheckSuiteEvent,
@@ -180,6 +191,28 @@ const azureDevOpsWebhook = route({
   },
 });
 
+const bitbucketWebhook = route({
+  method: "post",
+  path: "/api/bitbucket/webhook",
+  pattern: ["api", "bitbucket", "webhook"],
+  summary: "Handle Bitbucket Cloud webhook events",
+  tags: ["Webhooks"],
+  auth: { apiKey: false },
+  rbac: {
+    ungated:
+      "provider webhook: authenticated by the per-webhook HMAC secret, not a swarm principal",
+  },
+  responses: {
+    200: { description: "Event processed", schema: WebhookDispatchResultSchema },
+    401: { description: "Invalid signature" },
+    413: { description: "Body exceeds 1 MiB" },
+    503: { description: "Bitbucket integration not configured" },
+  },
+});
+
+/** Bitbucket Cloud event payloads are far below this. */
+const BITBUCKET_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
+
 const agentmailWebhook = route({
   method: "post",
   path: "/api/agentmail/webhook",
@@ -710,6 +743,114 @@ export async function handleWebhooks(
     return true;
   }
 
+  // Bitbucket Cloud webhook — HMAC over the raw body, event keyed by X-Event-Key
+  if (bitbucketWebhook.match(req.method, pathSegments)) {
+    if (!isBitbucketEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Bitbucket integration not configured" }));
+      return true;
+    }
+
+    // The body is read before the HMAC check, so cap it like the Chat SDK
+    // route: reject a declared or streamed body over the limit with 413.
+    if (enforceContentLengthCap(req, res, BITBUCKET_WEBHOOK_MAX_BODY_BYTES) === BODY_TOO_LARGE) {
+      return true;
+    }
+    const chunks: Buffer[] = [];
+    let receivedBytes = 0;
+    let tooLarge = false;
+    for await (const chunk of req) {
+      if (tooLarge) continue;
+      receivedBytes += (chunk as Buffer).byteLength;
+      if (receivedBytes > BITBUCKET_WEBHOOK_MAX_BODY_BYTES) {
+        tooLarge = true;
+        chunks.length = 0;
+        jsonError(res, `Payload too large (max ${BITBUCKET_WEBHOOK_MAX_BODY_BYTES} bytes)`, 413);
+        continue;
+      }
+      chunks.push(chunk as Buffer);
+    }
+    if (tooLarge) return true;
+    const rawBody = Buffer.concat(chunks).toString();
+
+    const signature = req.headers["x-hub-signature"] as string | undefined;
+    if (!verifyBitbucketWebhook(rawBody, signature)) {
+      console.log("[Bitbucket] Invalid webhook signature");
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid signature" }));
+      return true;
+    }
+
+    let body: unknown;
+    try {
+      body = JSON.parse(rawBody);
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      return true;
+    }
+
+    const eventKey = req.headers["x-event-key"] as string | undefined;
+    const requestUuid = req.headers["x-request-uuid"] as string | undefined;
+    if (isDuplicateBitbucketDelivery(requestUuid)) {
+      console.log(`[Bitbucket] Skipping duplicate delivery ${requestUuid}`);
+      bitbucketWebhook.respond(res, 200, { created: false });
+      return true;
+    }
+    console.log(`[Bitbucket] Received ${eventKey} event`);
+
+    try {
+      const result = await runBlockableHandler("Bitbucket", async () => {
+        switch (eventKey) {
+          case "pullrequest:created":
+            return await handleBitbucketPullRequestCreated(body);
+          case "pullrequest:comment_created":
+            return await handleBitbucketPullRequestCommentCreated(body);
+          case "pullrequest:fulfilled":
+            return await handleBitbucketPullRequestClosed(body, "merged");
+          case "pullrequest:rejected":
+            return await handleBitbucketPullRequestClosed(body, "declined");
+          default:
+            console.log(`[Bitbucket] Ignoring unsupported event type: ${eventKey}`);
+            return { created: false };
+        }
+      });
+
+      // Emit workflow trigger events for Bitbucket
+      const workflowEvent = {
+        "pullrequest:created": "created",
+        "pullrequest:comment_created": "commented",
+        "pullrequest:fulfilled": "merged",
+        "pullrequest:rejected": "declined",
+      }[eventKey ?? ""];
+      const prEvent = workflowEvent ? bitbucketPullRequestEventOf(body) : null;
+      if (workflowEvent && prEvent) {
+        const pr = prEvent.pullrequest;
+        const comment =
+          workflowEvent === "commented" ? bitbucketCommentEventOf(body)?.comment : undefined;
+        const user = comment?.user ?? prEvent.actor;
+        workflowEventBus.emit(`bitbucket.pull_request.${workflowEvent}`, {
+          repo: prEvent.repository.full_name,
+          number: pr.id,
+          ...(workflowEvent === "commented"
+            ? { body: comment?.content.raw }
+            : { title: pr.title, body: pr.description ?? undefined }),
+          action: workflowEvent,
+          user_login: user.account_id ?? user.nickname ?? user.display_name,
+        });
+      }
+
+      markBitbucketDeliveryProcessed(requestUuid);
+      bitbucketWebhook.respond(res, 200, result);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      console.error(`[Bitbucket] Error handling ${eventKey} event: ${scrubSecrets(errorMessage)}`);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal server error" }));
+    }
+    return true;
+  }
+
   // AgentMail webhook — needs raw body for Svix signature verification
   if (agentmailWebhook.match(req.method, pathSegments)) {
     if (!isAgentMailEnabled()) {

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

@@ -1,5 +1,7 @@
+import type { TelegramMessage } from "@chat-adapter/telegram";
 import type { Adapter, Logger } from "chat";
 import { type ChatSdkAdapterName, type ResolvedAdapterConfig, readApiUrlOverrides } from "./config";
+import { isTelegramReplyToBot, type TelegramRawMessage } from "./facts";
 import { withInfoFilter } from "./logger";
 import { getChatSdkTestHooks } from "./test-hooks";
 
@@ -61,11 +63,29 @@ export async function loadAdapter(
   const base = { ...config, apiUrl, logger };
   switch (name) {
     case "telegram": {
-      const { createTelegramAdapter } = await import("@chat-adapter/telegram");
+      const { TelegramAdapter } = await import("@chat-adapter/telegram");
+      // The adapter's `mentionOnReply` skips a reply whose target id equals
+      // `message_thread_id`, meant for forum topic roots. A plain supergroup
+      // reply to a bot message that starts a reply chain has that same shape,
+      // so it was never a mention and never reached a handler. Core decides
+      // with `is_topic_message`, as the task header facts do.
+      class SwarmTelegramAdapter extends TelegramAdapter {
+        protected override isBotMentioned(message: TelegramMessage, text: string): boolean {
+          return (
+            super.isBotMentioned(message, text) ||
+            (String(message.from?.id) !== this.botUserId &&
+              isTelegramReplyToBot(message as TelegramRawMessage, this.botUserId))
+          );
+        }
+      }
       // Explicit `false` blocks the TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS env fallback.
-      return createTelegramAdapter({ ...base, allowUnverifiedWebhooks: false } as Parameters<
-        typeof createTelegramAdapter
-      >[0]);
+      // Explicit `true` makes a reply to the bot a mention whatever
+      // TELEGRAM_MENTION_ON_REPLY says.
+      return new SwarmTelegramAdapter({
+        ...base,
+        allowUnverifiedWebhooks: false,
+        mentionOnReply: true,
+      } as ConstructorParameters<typeof TelegramAdapter>[0]);
     }
     case "slack": {
       const { createSlackAdapter } = await import("@chat-adapter/slack");

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

@@ -9,7 +9,9 @@
  * row. The task is created in `draft` while its uploads run, with its lease
  * renewed, so no worker can claim it before its attachments exist. Every file
  * also stays in the task text as a `[File: ...]` line. Only a fetch failure is
- * flagged there; upload and record failures are logged.
+ * flagged there; upload and record failures are logged. Audio files (voice
+ * notes) get their transcript in the task text when transcription is
+ * configured, and keep the audio attached.
  */
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -21,12 +23,28 @@ import { providerPath } from "@/fs/provider";
 import { getFileStorageProvider } from "@/fs/registry";
 import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import type { AgentTask, CreateTaskOptions } from "@/types";
+import { transcribeAudioNotes } from "@/utils/transcription";
 import { errorMessage } from "./logger";
 
 /** How often a draft's lease is renewed while its uploads run; the sweep waits 5 minutes. */
 const DRAFT_LEASE_REFRESH_MS = 60_000;
 /** A file a user sent the bot, like one uploaded from the dashboard composer. */
-const SHARED_FILE_INTENT = "user-upload";
+export const SHARED_FILE_INTENT = "user-upload";
+
+const MB = 1024 * 1024;
+/**
+ * Per-file inbound cap by adapter. A Telegram bot can download at most 20 MB
+ * through `getFile`; a larger file fails at Telegram before our own cap.
+ * Other adapters use the task attachment cap.
+ */
+const CHAT_INBOUND_FILE_LIMITS: Record<string, number> = { telegram: 20 * MB };
+
+export function chatInboundFileLimit(adapter: string): number {
+  return Math.min(
+    CHAT_INBOUND_FILE_LIMITS[adapter] ?? MAX_TASK_ATTACHMENT_BYTES,
+    MAX_TASK_ATTACHMENT_BYTES,
+  );
+}
 
 /**
  * One attachment of a buffered chat message. `id` is `<messageId>-<n>` with
@@ -43,7 +61,8 @@ export interface ChatFile {
   attachment: Attachment;
 }
 
-export type ChatFileFailure = { file: ChatFile; reason: string };
+/** `tooLarge` marks a file over the inbound cap; the user gets a reply naming it. */
+export type ChatFileFailure = { file: ChatFile; reason: string; tooLarge?: boolean };
 
 export type FetchedChatFile = { file: ChatFile; path: string; sizeBytes: number; sha256: string };
 
@@ -55,7 +74,7 @@ export type InboundChatFiles = {
   [Symbol.asyncDispose](): Promise<void>;
 };
 
-function formatFileSize(bytes: number): string {
+export function formatFileSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -81,20 +100,71 @@ export function toChatFiles(
 
 /**
  * `[File: <name> (<mime>, <size>) id=<id>]` per file, followed by
- * `(not attached: <reason>)` when the file never reached the task.
+ * `(not attached: <reason>)` when the file never reached the task, and by the
+ * file's note (a voice-note transcript) on the next line.
  */
-export function buildChatAttachmentText(files: ChatFile[], failed: ChatFileFailure[] = []): string {
+export function buildChatAttachmentText(
+  files: ChatFile[],
+  failed: ChatFileFailure[] = [],
+  notes: Map<string, string> = new Map(),
+): string {
   const reasons = new Map(failed.map((f) => [f.file.id, f.reason]));
   return files
     .map((f) => {
       const size = typeof f.size === "number" ? formatFileSize(f.size) : "unknown size";
       const line = `[File: ${f.name} (${f.mimeType ?? "unknown type"}, ${size}) id=${f.id}]`;
       const reason = reasons.get(f.id);
-      return reason ? `${line} (not attached: ${reason})` : line;
+      const note = notes.get(f.id);
+      return [reason ? `${line} (not attached: ${reason})` : line, note].filter(Boolean).join("\n");
     })
     .join("\n");
 }
 
+/**
+ * A sender-chosen file name as an inline code span, so the bot's reply shows it
+ * as literal text and never renders a link, image or heading from it. Backslash
+ * escapes are not enough: the Chat SDK parser still autolinks bare URLs.
+ */
+function markdownLiteral(value: string): string {
+  const text = value.replace(/[\r\n]+/g, " ");
+  const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(longestRun + 1);
+  // CommonMark strips one space from each end of a padded span.
+  const pad = /^[` ]|[` ]$/.test(text) ? " " : "";
+  return `${fence}${pad}${text}${pad}${fence}`;
+}
+
+/** The reply posted to the thread when files were over the inbound cap. */
+export function formatTooLargeReply(failed: ChatFileFailure[]): string {
+  const lines = failed.map((f) => `- ${markdownLiteral(f.file.name)}: ${f.reason}`);
+  return [
+    `Too large to read, so the swarm did not get ${failed.length === 1 ? "this file" : "these files"}:`,
+    ...lines,
+    "Send a smaller file or a link.",
+  ].join("\n");
+}
+
+/**
+ * Transcribe every fetched audio file. Returns one task-text note per file:
+ * the transcript, the failure, or (when no provider is configured) a line
+ * saying so. Never throws.
+ */
+export async function transcribeChatAudio(
+  fetched: FetchedChatFile[],
+): Promise<Map<string, string>> {
+  return transcribeAudioNotes(
+    fetched
+      .filter(({ file }) => file.attachment.type === "audio")
+      .map(({ file, path }) => ({
+        key: file.id,
+        name: file.name,
+        data: Bun.file(path),
+        mimeType: file.mimeType,
+      })),
+    "[chat-sdk]",
+  );
+}
+
 async function readAttachment(attachment: Attachment): Promise<Uint8Array> {
   if (attachment.data instanceof Blob) return new Uint8Array(await attachment.data.arrayBuffer());
   if (attachment.data) return new Uint8Array(attachment.data);
@@ -119,17 +189,25 @@ export async function fetchChatFiles(files: ChatFile[]): Promise<InboundChatFile
   };
   if (files.length === 0) return result;
 
-  const limit = `larger than the ${MAX_TASK_ATTACHMENT_BYTES / (1024 * 1024)} MB limit`;
+  const tooLarge = (file: ChatFile, size: number): ChatFileFailure => {
+    const limit = chatInboundFileLimit(file.adapter);
+    const platform = file.adapter.charAt(0).toUpperCase() + file.adapter.slice(1);
+    return {
+      file,
+      reason: `too large (${formatFileSize(size)}, the limit for files sent to the ${platform} bot is ${formatFileSize(limit)})`,
+      tooLarge: true,
+    };
+  };
   dir = await mkdtemp(join(tmpdir(), "chat-files-"));
   for (const [index, file] of files.entries()) {
-    if (typeof file.size === "number" && file.size > MAX_TASK_ATTACHMENT_BYTES) {
-      result.failed.push({ file, reason: limit });
+    if (typeof file.size === "number" && file.size > chatInboundFileLimit(file.adapter)) {
+      result.failed.push(tooLarge(file, file.size));
       continue;
     }
     try {
       const bytes = await readAttachment(file.attachment);
-      if (bytes.byteLength > MAX_TASK_ATTACHMENT_BYTES) {
-        result.failed.push({ file, reason: limit });
+      if (bytes.byteLength > chatInboundFileLimit(file.adapter)) {
+        result.failed.push(tooLarge(file, bytes.byteLength));
         continue;
       }
       const path = join(dir, String(index));

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

@@ -0,0 +1,138 @@
+import type { Message, Thread } from "chat";
+
+/** Why a message counts as meant for the swarm. `none`: it reached the router unaddressed. */
+export type ChatAddressedReason =
+  | "dm"
+  | "mention"
+  | "reply-to-bot"
+  | "requester-follow-up"
+  | "none";
+
+/**
+ * Facts about one inbound message that only core can read: the chat it came
+ * from (Telegram `message.raw.chat`) and whether it answers the bot.
+ */
+export interface ChatMessageFacts {
+  /** Platform chat type, such as Telegram `private`, `group` or `supergroup`. */
+  chatType?: string;
+  isForum?: boolean;
+  /** Group or channel title. */
+  title?: string;
+  /** Forum topic: `"<name>"` when the update carries it, else `#<thread id>`. */
+  topic?: string;
+  /** The sender as people know them: `Name (@username)`. */
+  from: string;
+  /** The message replies to one of the bot's own messages. */
+  replyToBot: boolean;
+  /** Start of the message it replies to. */
+  replyToSnippet?: string;
+}
+
+const SNIPPET_MAX = 80;
+
+export interface TelegramRawMessage {
+  message_id?: number;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  chat?: { type?: string; title?: string; is_forum?: boolean };
+  from?: { first_name?: string; last_name?: string; username?: string };
+  reply_to_message?: {
+    message_id?: number;
+    from?: { id?: number | string };
+    text?: string;
+    caption?: string;
+    forum_topic_created?: { name?: string };
+  };
+}
+
+function snippet(text: string | undefined): string | undefined {
+  const flat = text?.replace(/\s+/g, " ").trim();
+  if (!flat) return undefined;
+  return flat.length > SNIPPET_MAX ? `${flat.slice(0, SNIPPET_MAX)}...` : flat;
+}
+
+function personLabel(name: string | undefined, username: string | undefined, fallback: string) {
+  if (name && username && name !== username) return `${name} (@${username})`;
+  if (username) return `@${username}`;
+  return name || fallback;
+}
+
+/**
+ * In a forum topic every plain message replies to the topic's creation
+ * message, so that reply is the topic, not an answer to anyone. Only
+ * `is_topic_message` marks a topic: a plain supergroup reply also carries
+ * `message_thread_id`, the id of its reply chain's first message.
+ */
+function replyIsTopicRoot(raw: TelegramRawMessage): boolean {
+  const reply = raw.reply_to_message;
+  return (
+    reply !== undefined &&
+    (reply.forum_topic_created !== undefined ||
+      (raw.is_topic_message === true && reply.message_id === raw.message_thread_id))
+  );
+}
+
+/** The raw Telegram message replies to one of the bot's own messages, not to a forum topic root. */
+export function isTelegramReplyToBot(raw: TelegramRawMessage, botUserId?: string): boolean {
+  const fromId = raw.reply_to_message?.from?.id;
+  return (
+    !replyIsTopicRoot(raw) &&
+    fromId !== undefined &&
+    botUserId !== undefined &&
+    String(fromId) === botUserId
+  );
+}
+
+function telegramFacts(raw: TelegramRawMessage, message: Message, botUserId?: string) {
+  const reply = raw.reply_to_message;
+  const topicRoot = replyIsTopicRoot(raw);
+  const realReply = reply && !topicRoot ? reply : undefined;
+  const topicName = topicRoot ? reply?.forum_topic_created?.name : undefined;
+  const name = [raw.from?.first_name, raw.from?.last_name].filter(Boolean).join(" ").trim();
+  return {
+    chatType: raw.chat?.type,
+    isForum: raw.chat?.is_forum === true ? true : undefined,
+    title: raw.chat?.title,
+    topic:
+      raw.is_topic_message === true && raw.message_thread_id !== undefined
+        ? topicName
+          ? `"${topicName}"`
+          : `#${raw.message_thread_id}`
+        : undefined,
+    from: personLabel(name || undefined, raw.from?.username, message.author.userId),
+    replyToBot: isTelegramReplyToBot(raw, botUserId),
+    replyToSnippet: snippet(realReply?.text ?? realReply?.caption),
+  } satisfies ChatMessageFacts;
+}
+
+/** Read the chat facts of one message. Telegram reads the raw update; other adapters the SDK message. */
+export function readChatMessageFacts(thread: Thread, message: Message): ChatMessageFacts {
+  const raw = message.raw as TelegramRawMessage | undefined;
+  if (thread.adapter.name === "telegram" && raw && typeof raw === "object") {
+    return telegramFacts(raw, message, thread.adapter.botUserId);
+  }
+  const { fullName, userName, userId } = message.author;
+  return {
+    chatType: thread.isDM ? "dm" : undefined,
+    from: personLabel(fullName || undefined, userName || undefined, userId),
+    replyToBot: message.replyTo?.author.isMe === true,
+    replyToSnippet: snippet(message.replyTo?.text),
+  };
+}
+
+/** One line of facts for the task header: `telegram · supergroup "Life" · from: ... · addressed: ...`. */
+export function formatChatHeaderFacts(
+  adapter: string,
+  facts: ChatMessageFacts,
+  addressed: ChatAddressedReason,
+): string {
+  // Title, topic and sender are user-set: one line each, so none can forge a header line.
+  const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+  const parts = [adapter];
+  if (facts.chatType)
+    parts.push(facts.title ? `${facts.chatType} "${oneLine(facts.title)}"` : facts.chatType);
+  if (facts.isForum) parts.push(facts.topic ? `forum topic ${oneLine(facts.topic)}` : "forum");
+  parts.push(`from: ${oneLine(facts.from)}`, `addressed: ${addressed}`);
+  if (facts.replyToSnippet) parts.push(`reply-to: "${facts.replyToSnippet}"`);
+  return parts.join(" · ");
+}