@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/messaging/providers/discord/send.ts

@@ -0,0 +1,212 @@
+/**
+ * Discord outbound message orchestration.
+ *
+ * Splits replies into Discord-sized chunks (see ./render.ts) and uploads
+ * attachments, by calling the Discord REST API directly via ./api.ts.
+ */
+
+import { getAttachmentContent } from "../../../persistence/attachments-store.js";
+import type { RuntimeAttachmentMetadata } from "../../../runtime/http-types.js";
+import { getLogger } from "../../../util/logger.js";
+import {
+  callDiscordApi,
+  callDiscordApiMultipart,
+  type DiscordMessage,
+  DiscordNonRetryableError,
+} from "./api.js";
+import { renderDiscordMessages } from "./render.js";
+
+const log = getLogger("discord-send");
+
+/**
+ * Mention types Discord is allowed to resolve in an outbound message.
+ *
+ * The agent composes this text, and text it authored (or echoed from an
+ * untrusted inbound message) must never be able to ping a whole server or a
+ * whole role. `users` is kept so the assistant can address a person directly,
+ * which is ordinary Discord conversation; `everyone` and `roles` are withheld.
+ *
+ * This mirrors the invite scope the setup skill requests, which deliberately
+ * excludes Mention Everyone, and closes the role-mention gap that permission
+ * alone leaves open.
+ */
+const DISCORD_ALLOWED_MENTIONS = { parse: ["users"] } as const;
+
+/**
+ * Upper bound on an outbound attachment. Discord's real limit is the guild's
+ * boost tier (10 MiB with no boosts, more above that), which the API does not
+ * expose here, so the client-side guard is only the ceiling no tier exceeds:
+ * past it the upload is provably futile and not worth the bandwidth. Anything
+ * under it is attempted and, if the guild's own tier rejects it, reported
+ * through the same failure notice as any other attachment error.
+ */
+const DISCORD_MAX_ATTACHMENT_BYTES = 100 * 1024 * 1024;
+
+/** Send target for one Discord delivery. */
+export interface DiscordSendTarget {
+  /**
+   * Snowflake of the channel the message is posted to. For a threaded reply
+   * this is the thread's own id, because a Discord thread *is* a channel and
+   * `POST /channels/{id}/messages` addresses it directly.
+   */
+  channelId: string;
+}
+
+function messagesRoute(target: DiscordSendTarget): string {
+  return `/channels/${encodeURIComponent(target.channelId)}/messages`;
+}
+
+/** Outcome of a Discord reply send. */
+export interface DiscordSendResult {
+  /**
+   * Channel-native id of the last chunk sent, for callers that need to address
+   * the message later. Undefined when the API response carried no id.
+   */
+  lastMessageId?: string;
+}
+
+/**
+ * Send a text reply, split across as many messages as Discord's content cap
+ * requires. Chunks post in order so the reply reads top to bottom.
+ */
+export async function sendDiscordReply(
+  target: DiscordSendTarget,
+  text: string,
+): Promise<DiscordSendResult> {
+  const chunks = renderDiscordMessages(text);
+  if (chunks.length === 0) {
+    return {};
+  }
+
+  let lastMessageId: string | undefined;
+  for (const chunk of chunks) {
+    const sent = await callDiscordApi<DiscordMessage>(
+      "POST",
+      messagesRoute(target),
+      {
+        content: chunk,
+        allowed_mentions: DISCORD_ALLOWED_MENTIONS,
+      },
+    );
+    lastMessageId = typeof sent?.id === "string" ? sent.id : undefined;
+  }
+
+  log.debug(
+    { channelId: target.channelId, chunks: chunks.length },
+    "Discord reply sent",
+  );
+  return lastMessageId !== undefined ? { lastMessageId } : {};
+}
+
+export interface DiscordAttachmentResult {
+  allFailed: boolean;
+  failureCount: number;
+  totalCount: number;
+}
+
+/**
+ * Upload attachments to a Discord channel, one request per file so a single
+ * rejection does not take the rest of the batch with it.
+ *
+ * Discord's documented upload shape is a `multipart/form-data` body whose
+ * files ride as `files[n]` parts, with the JSON body moved to `payload_json`
+ * and each file declared in an `attachments` array keyed by the same `n`.
+ */
+export async function sendDiscordAttachments(
+  target: DiscordSendTarget,
+  attachments: RuntimeAttachmentMetadata[],
+): Promise<DiscordAttachmentResult> {
+  const failures: string[] = [];
+
+  /**
+   * Name a failed file for the channel notice. A refusal Discord explains
+   * (over the guild's upload limit, missing Attach Files) is worth passing on,
+   * since the reader can act on it; anything else stays bare, because the
+   * detail is a transport error the reader cannot do anything about.
+   */
+  const describeFailure = (name: string, err: unknown): string =>
+    err instanceof DiscordNonRetryableError
+      ? `${name} (Discord returned ${err.status})`
+      : name;
+
+  for (const meta of attachments) {
+    const displayName = meta.filename ?? meta.id;
+
+    if (
+      meta.sizeBytes !== undefined &&
+      meta.sizeBytes > DISCORD_MAX_ATTACHMENT_BYTES
+    ) {
+      log.warn(
+        { attachmentId: meta.id, sizeBytes: meta.sizeBytes },
+        "Skipping oversized outbound attachment",
+      );
+      failures.push(displayName);
+      continue;
+    }
+
+    try {
+      const content = getAttachmentContent(meta.id);
+      if (!content) {
+        log.error(
+          { attachmentId: meta.id },
+          "Attachment content not found in store",
+        );
+        failures.push(displayName);
+        continue;
+      }
+
+      if (content.length > DISCORD_MAX_ATTACHMENT_BYTES) {
+        log.warn(
+          { attachmentId: meta.id, sizeBytes: content.length },
+          "Skipping oversized outbound attachment (detected after read)",
+        );
+        failures.push(displayName);
+        continue;
+      }
+
+      const blob = new Blob([new Uint8Array(content)], {
+        type: meta.mimeType ?? "application/octet-stream",
+      });
+      const form = new FormData();
+      form.set(
+        "payload_json",
+        JSON.stringify({
+          attachments: [{ id: 0, filename: displayName }],
+          allowed_mentions: DISCORD_ALLOWED_MENTIONS,
+        }),
+      );
+      form.set("files[0]", blob, displayName);
+
+      await callDiscordApiMultipart(messagesRoute(target), form);
+
+      log.debug(
+        { channelId: target.channelId, attachmentId: meta.id },
+        "Attachment sent to Discord",
+      );
+    } catch (err) {
+      log.error(
+        { err, attachmentId: meta.id, filename: displayName },
+        "Failed to send attachment to Discord",
+      );
+      failures.push(describeFailure(displayName, err));
+    }
+  }
+
+  if (failures.length > 0) {
+    const notice = `⚠️ ${failures.length} attachment(s) could not be delivered: ${failures.join(", ")}`;
+    try {
+      await sendDiscordReply(target, notice);
+    } catch (err) {
+      log.error(
+        { err, channelId: target.channelId },
+        "Failed to send attachment failure notice",
+      );
+    }
+  }
+
+  return {
+    allFailed: failures.length === attachments.length,
+    failureCount: failures.length,
+    totalCount: attachments.length,
+  };
+}

package/src/messaging/providers/discord/transport.ts

@@ -0,0 +1,81 @@
+import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
+
+import { getLogger } from "../../../util/logger.js";
+import type {
+  CallbackContext,
+  ChannelTransport,
+} from "../channel-transport.js";
+import { openDiscordDmChannel } from "./api.js";
+import type { DiscordSendTarget } from "./send.js";
+import { sendDiscordAttachments, sendDiscordReply } from "./send.js";
+
+const log = getLogger("discord-transport");
+
+/**
+ * Resolve where a reply is posted.
+ *
+ * The gateway normalizer sets `conversationExternalId` (which arrives as
+ * `payload.chatId`) to the *parent* channel for a thread message, mirroring
+ * Slack's channel + thread_ts split, and carries the thread's own snowflake on
+ * the callback URL's `threadId` param. A Discord thread is itself a channel,
+ * so a threaded reply posts to the thread id and everything else to the
+ * channel id.
+ *
+ * The `dm` param inverts what `chatId` means: it marks the value as a
+ * *recipient user* snowflake to be reached privately, which is resolved to a
+ * DM channel here. Callers that address a person rather than a room set it,
+ * because a Discord user id and a channel id are both bare snowflakes and
+ * nothing in the value itself says which one arrived.
+ *
+ * `channel` and `threadId` are the only coordinates delivery needs;
+ * `POST /channels/{id}/messages` addresses a channel and nothing more.
+ */
+async function sendTarget(
+  ctx: CallbackContext,
+  chatId: string,
+): Promise<DiscordSendTarget> {
+  if (ctx.params.dm === "1") {
+    return { channelId: await openDiscordDmChannel(chatId) };
+  }
+  return { channelId: ctx.params.threadId?.trim() || chatId };
+}
+
+export const discordTransport: ChannelTransport = {
+  channel: "discord",
+
+  async deliver(ctx, payload) {
+    const { chatId, text, attachments, approval } = payload;
+    const target = await sendTarget(ctx, chatId);
+
+    let sentId: string | undefined;
+    if (text) {
+      const result = await sendDiscordReply(target, text);
+      sentId = result.lastMessageId;
+    } else if (approval) {
+      // Approvals deliver as plain text, so the prompt is readable but not
+      // clickable. Discord is not a guardian channel: approval prompts are
+      // actioned from the guardian's own channel, not from here.
+      const result = await sendDiscordReply(
+        target,
+        approval.plainTextFallback || "Approval required",
+      );
+      sentId = result.lastMessageId;
+    }
+
+    if (attachments && attachments.length > 0) {
+      const result = await sendDiscordAttachments(target, attachments);
+      if (result.allFailed && !text) {
+        throw new ChannelDeliveryError(
+          502,
+          `All ${result.failureCount} attachments failed to deliver`,
+        );
+      }
+    }
+
+    log.info(
+      { channelId: target.channelId, hasText: !!text },
+      "Discord reply delivered (direct)",
+    );
+    return { ok: true, ts: sentId };
+  },
+};

package/src/messaging/providers/index.ts

@@ -5,7 +5,7 @@
  * lives in `callback-routing.ts`. The gateway-client consults
  * `isDirectDelivery()` before falling back to the HTTP proxy path.
  *
- * Supported: Slack, Telegram, WhatsApp, A2A.
+ * Supported: Slack, Telegram, WhatsApp, A2A, Discord.
  */
 
 import type {
@@ -17,6 +17,7 @@ import { a2aTransport } from "./a2a/transport.js";
 import type { DirectDeliveryChannel } from "./callback-routing.js";
 import { channelForCallback } from "./callback-routing.js";
 import type { CallbackContext, ChannelTransport } from "./channel-transport.js";
+import { discordTransport } from "./discord/transport.js";
 import { slackTransport } from "./slack/transport.js";
 import { telegramTransport } from "./telegram-bot/transport.js";
 import { whatsappTransport } from "./whatsapp/transport.js";
@@ -30,6 +31,7 @@ const TRANSPORTS: Record<DirectDeliveryChannel, ChannelTransport> = {
   telegram: telegramTransport,
   whatsapp: whatsappTransport,
   a2a: a2aTransport,
+  discord: discordTransport,
 };
 
 /**

package/src/messaging/providers/retry-policy.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+
+import type { RetryableCall } from "./retry-policy.js";
+import {
+  computeRetryDelayMs,
+  isRetryableStatus,
+  MAX_TIMER_DELAY_MS,
+  retryableCall,
+} from "./retry-policy.js";
+
+describe("isRetryableStatus", () => {
+  test("retries rate limits and server faults", () => {
+    expect(isRetryableStatus(429)).toBe(true);
+    expect(isRetryableStatus(500)).toBe(true);
+    expect(isRetryableStatus(502)).toBe(true);
+    expect(isRetryableStatus(503)).toBe(true);
+  });
+
+  test("does not retry a request the server rejected on its merits", () => {
+    // A retry reproduces these exactly, so repeating them only burns quota.
+    for (const status of [400, 401, 403, 404, 413, 422]) {
+      expect(isRetryableStatus(status)).toBe(false);
+    }
+  });
+
+  test("does not retry success", () => {
+    expect(isRetryableStatus(200)).toBe(false);
+    expect(isRetryableStatus(204)).toBe(false);
+  });
+});
+
+describe("computeRetryDelayMs", () => {
+  test("honours a Retry-After given in seconds", () => {
+    expect(computeRetryDelayMs(1, 1000, "3")).toBe(3000);
+    // Discord sends fractional seconds.
+    expect(computeRetryDelayMs(1, 1000, "0.75")).toBe(750);
+  });
+
+  test("honours a Retry-After given as an HTTP date", () => {
+    const target = new Date(Date.now() + 5000).toUTCString();
+    const delay = computeRetryDelayMs(1, 1000, target);
+    // Whole-second date resolution, so allow the truncation either way.
+    expect(delay).toBeGreaterThan(3000);
+    expect(delay).toBeLessThanOrEqual(5000);
+  });
+
+  test("caps a server-advertised wait at the caller's bound", () => {
+    // A caller holding a lock across the wait passes a small bound so a long
+    // rate-limit window fails the call instead of stalling behind it.
+    expect(computeRetryDelayMs(1, 1000, "3600", 60_000)).toBe(60_000);
+  });
+
+  test("caps at the timer ceiling by default, so the wait is real", () => {
+    // Past this setTimeout fires immediately, turning a long wait into none.
+    expect(computeRetryDelayMs(1, 1000, "999999999")).toBe(MAX_TIMER_DELAY_MS);
+  });
+
+  test("backs off exponentially when the server gives no hint", () => {
+    for (const [attempt, base] of [
+      [1, 1000],
+      [2, 2000],
+      [3, 4000],
+    ] as const) {
+      const delay = computeRetryDelayMs(attempt, 1000, null);
+      expect(delay).toBeGreaterThanOrEqual(base);
+      // Jitter is additive and bounded at half the exponential term.
+      expect(delay).toBeLessThanOrEqual(base * 1.5);
+    }
+  });
+
+  test("jitters, so callers that failed together do not resume together", () => {
+    const delays = new Set(
+      Array.from({ length: 20 }, () => computeRetryDelayMs(3, 1000, null)),
+    );
+    expect(delays.size).toBeGreaterThan(1);
+  });
+
+  test("falls back to backoff for unusable Retry-After values", () => {
+    for (const value of ["", "soon", "-5", "0"]) {
+      const delay = computeRetryDelayMs(1, 1000, value);
+      expect(delay).toBeGreaterThanOrEqual(1000);
+      expect(delay).toBeLessThanOrEqual(1500);
+    }
+  });
+
+  test("ignores an already-elapsed Retry-After date", () => {
+    const past = new Date(Date.now() - 10_000).toUTCString();
+    const delay = computeRetryDelayMs(1, 1000, past);
+    expect(delay).toBeGreaterThanOrEqual(1000);
+    expect(delay).toBeLessThanOrEqual(1500);
+  });
+});
+
+describe("retryableCall", () => {
+  const silent = { debug() {}, warn() {} };
+
+  function spec<T>(overrides: Partial<RetryableCall<T>>): RetryableCall<T> {
+    return {
+      provider: "Test",
+      operation: "doThing",
+      maxRetries: 2,
+      initialBackoffMs: 1,
+      log: silent,
+      doFetch: async () => new Response("{}", { status: 200 }),
+      nonRetryableError: ({ message }) => new Error(message),
+      decode: (body) => JSON.parse(body) as T,
+      ...overrides,
+    } as RetryableCall<T>;
+  }
+
+  test("returns the decoded body without retrying on success", async () => {
+    let calls = 0;
+    const result = await retryableCall<{ v: number }>(
+      spec({
+        doFetch: async () => {
+          calls++;
+          return new Response(JSON.stringify({ v: 7 }), { status: 200 });
+        },
+      }),
+    );
+    expect(result).toEqual({ v: 7 });
+    expect(calls).toBe(1);
+  });
+
+  test("repeats a rate limit and returns the eventual success", async () => {
+    let calls = 0;
+    const result = await retryableCall<{ ok: boolean }>(
+      spec({
+        doFetch: async () => {
+          calls++;
+          return calls === 1
+            ? new Response("{}", { status: 429 })
+            : new Response(JSON.stringify({ ok: true }), { status: 200 });
+        },
+      }),
+    );
+    expect(result).toEqual({ ok: true });
+    expect(calls).toBe(2);
+  });
+
+  test("throws immediately on a status a retry would reproduce", async () => {
+    let calls = 0;
+    await expect(
+      retryableCall(
+        spec({
+          doFetch: async () => {
+            calls++;
+            return new Response('{"m":"nope"}', { status: 403 });
+          },
+          nonRetryableError: ({ status, message }) =>
+            new Error(`terminal ${status}: ${message}`),
+        }),
+      ),
+    ).rejects.toThrow(/terminal 403/);
+    // The point of the distinction: a 403 is not retried.
+    expect(calls).toBe(1);
+  });
+
+  test("surfaces the last failure, not a generic one, after exhausting retries", async () => {
+    await expect(
+      retryableCall(
+        spec({
+          maxRetries: 1,
+          doFetch: async () =>
+            new Response('{"detail":"upstream on fire"}', { status: 503 }),
+          detailFrom: (body) =>
+            (JSON.parse(body) as { detail?: string }).detail,
+        }),
+      ),
+    ).rejects.toThrow(/upstream on fire/);
+  });
+
+  test("retries a transport error and reports it if it never recovers", async () => {
+    let calls = 0;
+    await expect(
+      retryableCall(
+        spec({
+          maxRetries: 1,
+          doFetch: async () => {
+            calls++;
+            throw new Error("socket hang up");
+          },
+        }),
+      ),
+    ).rejects.toThrow(/socket hang up/);
+    expect(calls).toBe(2);
+  });
+
+  test("redacts before text reaches a message", async () => {
+    // Providers whose errors echo a credential rely on this.
+    await expect(
+      retryableCall(
+        spec({
+          maxRetries: 0,
+          doFetch: async () => new Response("token=SECRET", { status: 500 }),
+          redact: (v) => v.replace("SECRET", "[REDACTED]"),
+        }),
+      ),
+    ).rejects.toThrow(/\[REDACTED\]/);
+    await expect(
+      retryableCall(
+        spec({
+          maxRetries: 0,
+          doFetch: async () => new Response("token=SECRET", { status: 500 }),
+          redact: (v) => v.replace("SECRET", "[REDACTED]"),
+        }),
+      ),
+    ).rejects.not.toThrow(/SECRET(?!\])/);
+  });
+
+  test("prefers a body-carried Retry-After over the header", async () => {
+    const seen: (string | null)[] = [];
+    let calls = 0;
+    await retryableCall(
+      spec({
+        doFetch: async () => {
+          calls++;
+          return calls === 1
+            ? new Response('{"retry_after":0.001}', {
+                status: 429,
+                headers: { "retry-after": "999" },
+              })
+            : new Response("{}", { status: 200 });
+        },
+        retryAfterFrom: (_r, body) => {
+          const v = (JSON.parse(body) as { retry_after?: number }).retry_after;
+          const picked = v != null ? String(v) : null;
+          seen.push(picked);
+          return picked;
+        },
+      }),
+    );
+    // The header said 999 seconds; the body's value is the one used.
+    expect(seen).toEqual(["0.001"]);
+  });
+
+  test("passes an empty body to decode rather than assuming JSON", async () => {
+    // A 204 has nothing to parse, and only the caller knows what that means.
+    const result = await retryableCall<string>(
+      spec({
+        doFetch: async () => new Response(null, { status: 204 }),
+        decode: (body) => (body === "" ? "empty" : "unexpected"),
+      }),
+    );
+    expect(result).toBe("empty");
+  });
+});