@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/messaging/providers/__tests__/transport-dispatch.test.ts

@@ -36,11 +36,23 @@ const whatsapp = {
 const a2a = {
   deliverA2AReply: mock((..._args: unknown[]) => Promise.resolve({ ok: true })),
 };
+const discord = {
+  sendDiscordReply: mock((..._args: unknown[]) =>
+    Promise.resolve({ lastMessageId: "discord-id" }),
+  ),
+  sendDiscordTypingIndicator: mock((..._args: unknown[]) =>
+    Promise.resolve(true),
+  ),
+  sendDiscordAttachments: mock((..._args: unknown[]) =>
+    Promise.resolve({ allFailed: false, failureCount: 0, totalCount: 0 }),
+  ),
+};
 
 mock.module("../slack/send.js", () => slack);
 mock.module("../telegram-bot/send.js", () => telegram);
 mock.module("../whatsapp/send.js", () => whatsapp);
 mock.module("../a2a/deliver.js", () => a2a);
+mock.module("../discord/send.js", () => discord);
 mock.module("../../../util/logger.js", () => ({
   getLogger: () => ({ debug() {}, info() {}, warn() {}, error() {} }),
 }));
@@ -57,7 +69,7 @@ function payload(
 }
 
 beforeEach(() => {
-  for (const group of [slack, telegram, whatsapp, a2a]) {
+  for (const group of [slack, telegram, whatsapp, a2a, discord]) {
     for (const spy of Object.values(group)) {
       spy.mockClear();
     }
@@ -78,19 +90,25 @@ describe("routing", () => {
     expect(
       getTransportForCallback(`${BASE}/deliver/a2a?taskId=t1`)?.channel,
     ).toBe("a2a");
+    expect(getTransportForCallback(`${BASE}/deliver/discord`)?.channel).toBe(
+      "discord",
+    );
   });
 
   test("isDirectDelivery is true for owned paths, false otherwise", () => {
     expect(isDirectDelivery(`${BASE}/deliver/slack`)).toBe(true);
     expect(isDirectDelivery(`${BASE}/deliver/a2a?taskId=t1`)).toBe(true);
-    expect(isDirectDelivery(`${BASE}/deliver/discord`)).toBe(false);
+    expect(isDirectDelivery(`${BASE}/deliver/discord`)).toBe(true);
     expect(isDirectDelivery(`${BASE}/v1/messages`)).toBe(false);
     expect(
       isDirectDelivery(
         `${BASE}/v1/internal/managed-gateway/outbound-send/?route_id=r1`,
       ),
     ).toBe(false);
-    expect(getTransportForCallback(`${BASE}/deliver/discord`)).toBeUndefined();
+    // `phone` is a canonical channel with no direct-delivery transport, so it
+    // stands in for the never-registered case discord used to cover.
+    expect(isDirectDelivery(`${BASE}/deliver/phone`)).toBe(false);
+    expect(getTransportForCallback(`${BASE}/deliver/phone`)).toBeUndefined();
   });
 });
 
@@ -203,12 +221,56 @@ describe("capability gating across channels", () => {
     expect(a2a.deliverA2AReply).toHaveBeenCalledTimes(1);
     expect(a2a.deliverA2AReply.mock.calls[0][0]).toBe(url);
   });
+
+  test("Discord text routes to sendDiscordReply, targeting the channel", async () => {
+    await deliverDirect(`${BASE}/deliver/discord`, payload({ text: "hi" }));
+    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+    expect(discord.sendDiscordReply.mock.calls[0][0]).toEqual({
+      channelId: "C1",
+    });
+    expect(discord.sendDiscordReply.mock.calls[0][1]).toBe("hi");
+  });
+
+  test("Discord threads a reply to the thread id, not the parent channel", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/discord?threadId=T9`,
+      payload({ text: "hi" }),
+    );
+    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+    // A Discord thread is itself a channel: the reply must post to the thread
+    // snowflake, never to the parent channel the payload's chatId carries.
+    expect(discord.sendDiscordReply.mock.calls[0][0]).toEqual({
+      channelId: "T9",
+    });
+  });
+
+  test("a typing payload to Discord falls through to deliver (no sendTyping)", async () => {
+    // Only the Telegram heartbeat produces `chatAction: "typing"`, and it is
+    // gated on sourceChannel === "telegram", so Discord can never receive one.
+    // The transport implements no sendTyping, so this falls through.
+    await deliverDirect(
+      `${BASE}/deliver/discord`,
+      payload({ chatAction: "typing", text: "hi" }),
+    );
+    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+  });
+
+  test("a Slack-only stream payload to Discord falls through to deliver", async () => {
+    await deliverDirect(
+      `${BASE}/deliver/discord`,
+      payload({
+        text: "hi",
+        slackStream: { action: "start", threadTs: "1700.5" },
+      }),
+    );
+    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe("unsupported callback", () => {
   test("throws when no transport owns the callback", async () => {
     await expect(
-      deliverDirect(`${BASE}/deliver/discord`, payload({ text: "hi" })),
+      deliverDirect(`${BASE}/deliver/phone`, payload({ text: "hi" })),
     ).rejects.toThrow(/unsupported callback/);
   });
 });

package/src/messaging/providers/callback-routing.ts

@@ -15,6 +15,7 @@ const DIRECT_DELIVERY_CHANNELS = [
   "telegram",
   "whatsapp",
   "a2a",
+  "discord",
 ] as const satisfies readonly ChannelId[];
 
 export type DirectDeliveryChannel = (typeof DIRECT_DELIVERY_CHANNELS)[number];

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

@@ -0,0 +1,312 @@
+/**
+ * Discord REST client for direct outbound messaging.
+ *
+ * Calls the Discord HTTP API directly using the `discord_channel:bot_token`
+ * credential, the same token the gateway's Discord Gateway client identifies
+ * with, read from the secure store rather than passed across the process
+ * boundary. Retry and error classification mirror the sibling Telegram client
+ * so delivery behaviour is consistent across channels.
+ *
+ * Wire shapes verified against the official docs:
+ *   https://docs.discord.com/developers/resources/message
+ *   https://docs.discord.com/developers/topics/rate-limits
+ *   https://docs.discord.com/developers/reference
+ */
+
+import { credentialKey } from "../../../security/credential-key.js";
+import { getSecureKeyResultAsync } from "../../../security/secure-keys.js";
+import { BackendUnavailableError, ConfigError } from "../../../util/errors.js";
+import { getLogger } from "../../../util/logger.js";
+import { retryableCall } from "../retry-policy.js";
+
+const log = getLogger("discord-api");
+
+const DISCORD_API_BASE_URL = "https://discord.com/api/v10";
+
+/**
+ * Discord requires HTTP API clients to identify themselves with a User-Agent
+ * of this documented form (`https://docs.discord.com/developers/reference`).
+ */
+const DISCORD_USER_AGENT =
+  "DiscordBot (https://github.com/vellum-ai/vellum-assistant, 1.0)";
+
+const DISCORD_DEFAULT_MAX_RETRIES = 3;
+const DISCORD_DEFAULT_INITIAL_BACKOFF_MS = 1000;
+const DISCORD_DEFAULT_TIMEOUT_MS = 15_000;
+
+/**
+ * Cap on a server-advertised `retry_after`. Discord can hand back a multi-hour
+ * wait when a bot is globally limited; sleeping that long inside a delivery
+ * would hold the per-conversation single-flight open indefinitely. Past this
+ * bound the call fails and the channel retry sweep owns the redelivery.
+ */
+const DISCORD_MAX_RETRY_AFTER_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+/**
+ * A Discord REST call that returned a non-retryable client error: a 4xx that
+ * is not a 429. The request itself is the problem (the channel, the
+ * permissions, or the payload), so retrying the same call is pointless.
+ *
+ * Callers branch on this type to degrade gracefully, e.g. an attachment that
+ * Discord refuses is reported to the channel instead of retried. Branch on the
+ * type rather than on Discord's numeric error code: the docs treat that code
+ * list as open, and new codes are added without notice.
+ */
+export class DiscordNonRetryableError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "DiscordNonRetryableError";
+    this.status = status;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface DiscordErrorBody {
+  message?: string;
+  retry_after?: number;
+  global?: boolean;
+}
+
+function parseErrorBody(body: string): DiscordErrorBody {
+  try {
+    return JSON.parse(body) as DiscordErrorBody;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The wait Discord asked for, as a `Retry-After` seconds value.
+ *
+ * Discord carries it in the 429 JSON body as well as the header, in seconds
+ * (fractional) either way, and the body is the more precise of the two.
+ */
+function retryAfterFrom(_response: Response, body: string): string | null {
+  const parsed = parseErrorBody(body);
+  return typeof parsed.retry_after === "number" && parsed.retry_after > 0
+    ? String(parsed.retry_after)
+    : null;
+}
+
+/**
+ * Run a Discord REST call with retries.
+ *
+ * `T | undefined` because an endpoint may answer 204 with no body; callers
+ * that need a response shape assert on it themselves.
+ */
+function discordCall<T>(
+  route: string,
+  doFetch: () => Promise<Response>,
+): Promise<T | undefined> {
+  return retryableCall<T | undefined>({
+    provider: "Discord",
+    operation: route,
+    maxRetries: DISCORD_DEFAULT_MAX_RETRIES,
+    initialBackoffMs: DISCORD_DEFAULT_INITIAL_BACKOFF_MS,
+    maxDelayMs: DISCORD_MAX_RETRY_AFTER_MS,
+    log,
+    doFetch,
+    detailFrom: (body) => parseErrorBody(body).message,
+    retryAfterFrom,
+    nonRetryableError: ({ status, message }) =>
+      new DiscordNonRetryableError(status, message),
+    decode: (body) => {
+      if (!body) {
+        return undefined;
+      }
+      try {
+        return JSON.parse(body) as T;
+      } catch {
+        throw new Error(
+          `Discord ${route} returned an unparseable response body`,
+        );
+      }
+    },
+  });
+}
+
+/**
+ * Run a Discord REST call with retries.
+ *
+ * Retryable: 429 (rate limited) and 5xx, plus transport failures. Everything
+ * else surfaces as {@link DiscordNonRetryableError}.
+ *
+ * `T | undefined` because an endpoint may answer 204 with no body; callers
+ * that need a response shape assert on it themselves.
+ */
+
+// ---------------------------------------------------------------------------
+// Credential resolution
+// ---------------------------------------------------------------------------
+
+async function resolveBotToken(): Promise<string> {
+  const result = await getSecureKeyResultAsync(
+    credentialKey("discord_channel", "bot_token"),
+  );
+  if (result.value) {
+    return result.value;
+  }
+  // Distinguish a transient credential-store outage from a token that was
+  // genuinely never set. Both surface as an absent value, but only the latter
+  // is an operator misconfiguration; the former is retryable infrastructure
+  // unavailability that callers should not treat as "not configured".
+  if (result.unreachable) {
+    throw new BackendUnavailableError("Discord credential store unreachable");
+  }
+  throw new ConfigError("Discord bot token not configured");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** The subset of Discord's message object that delivery reads back. */
+export interface DiscordMessage {
+  id: string;
+}
+
+/** The subset of Discord's channel object that DM resolution reads back. */
+interface DiscordChannel {
+  id: string;
+}
+
+/**
+ * Resolved DM channels, keyed by recipient user snowflake.
+ *
+ * The mapping is stable, so this never goes stale: Discord's create-DM route
+ * returns the existing channel when one exists rather than opening a second
+ * (https://docs.discord.com/developers/resources/user). The cache is here
+ * because that same page warns that opening DMs in volume gets a bot rate
+ * limited or blocked from opening new ones, and a per-recipient DM lane would
+ * otherwise re-open on every notice.
+ */
+const dmChannelIds = new Map<string, string>();
+
+/**
+ * Bound on the cache. Entries are one small string pair each, and the eviction
+ * below is insertion-order rather than least-recently-used: the entries this
+ * cache exists to protect (the guardian, a handful of contacts) are the ones
+ * created first, and evicting one only costs a single extra API call.
+ */
+const MAX_CACHED_DM_CHANNELS = 512;
+
+/**
+ * Opens already in progress, so concurrent callers for the same recipient
+ * share one request rather than racing to make the same one. A verification
+ * send and a guardian expiry notice can address the same person in the same
+ * tick, and the cache alone does not help there: neither has populated it yet.
+ */
+const inFlightDmOpens = new Map<string, Promise<string>>();
+
+/**
+ * Open the DM channel with a Discord user and return its snowflake.
+ *
+ * Discord has no "look up my DM with this person" route: a bot names a
+ * recipient and is handed the channel, creating it the first time and
+ * receiving the same one after that. So reaching one person privately is
+ * always this call followed by an ordinary channel send, and the DM channel is
+ * a resolved address rather than something the caller can be told up front.
+ */
+export function openDiscordDmChannel(recipientUserId: string): Promise<string> {
+  const cached = dmChannelIds.get(recipientUserId);
+  if (cached) {
+    return Promise.resolve(cached);
+  }
+
+  const existing = inFlightDmOpens.get(recipientUserId);
+  if (existing) {
+    return existing;
+  }
+
+  const open = (async (): Promise<string> => {
+    const channel = await callDiscordApi<DiscordChannel>(
+      "POST",
+      "/users/@me/channels",
+      { recipient_id: recipientUserId },
+    );
+    if (typeof channel?.id !== "string" || channel.id.length === 0) {
+      throw new Error(
+        "Discord create-DM returned no channel id for the recipient",
+      );
+    }
+
+    if (dmChannelIds.size >= MAX_CACHED_DM_CHANNELS) {
+      const oldest = dmChannelIds.keys().next();
+      if (!oldest.done) {
+        dmChannelIds.delete(oldest.value);
+      }
+    }
+    dmChannelIds.set(recipientUserId, channel.id);
+    log.debug({ recipientUserId }, "Opened Discord DM channel");
+    return channel.id;
+  })().finally(() => {
+    // Cleared on failure too, so a transient error does not pin every later
+    // caller to the same rejected promise.
+    inFlightDmOpens.delete(recipientUserId);
+  });
+
+  inFlightDmOpens.set(recipientUserId, open);
+  return open;
+}
+
+/** Drop the resolved and in-flight DM channel state. Test-only seam. */
+export function resetDiscordDmChannelCache(): void {
+  dmChannelIds.clear();
+  inFlightDmOpens.clear();
+}
+
+/** Call a Discord REST route with a JSON body. */
+export async function callDiscordApi<T>(
+  method: "POST" | "PATCH",
+  route: string,
+  body: Record<string, unknown>,
+): Promise<T | undefined> {
+  const botToken = await resolveBotToken();
+  return discordCall<T>(route, () =>
+    fetch(`${DISCORD_API_BASE_URL}${route}`, {
+      method,
+      headers: {
+        Authorization: `Bot ${botToken}`,
+        "Content-Type": "application/json",
+        "User-Agent": DISCORD_USER_AGENT,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(DISCORD_DEFAULT_TIMEOUT_MS),
+    }),
+  );
+}
+
+/**
+ * Call a Discord REST route with a `multipart/form-data` body.
+ *
+ * Discord's documented upload shape: files ride as `files[n]` parts and the
+ * JSON body moves to a `payload_json` part.
+ */
+export async function callDiscordApiMultipart<T>(
+  route: string,
+  form: FormData,
+): Promise<T | undefined> {
+  const botToken = await resolveBotToken();
+  return discordCall<T>(route, () =>
+    fetch(`${DISCORD_API_BASE_URL}${route}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bot ${botToken}`,
+        // Content-Type is deliberately unset so fetch derives the multipart
+        // boundary from the FormData body.
+        "User-Agent": DISCORD_USER_AGENT,
+      },
+      body: form,
+      signal: AbortSignal.timeout(DISCORD_DEFAULT_TIMEOUT_MS),
+    }),
+  );
+}

package/src/messaging/providers/discord/dm-delivery.test.ts

@@ -0,0 +1,204 @@
+/**
+ * The Discord private-delivery lane, asserted against a stubbed fetch.
+ *
+ * Discord has no route that looks a DM up by recipient, so reaching one person
+ * is always "open the channel, then post to it". Two things about that are
+ * silent when wrong and are pinned here: the open call must use the documented
+ * create-DM route, and a delivery marked `dm` must post to the channel that
+ * call returned rather than to the id it was handed. The second is the one
+ * that matters: the id handed in is a *user* snowflake, and a Discord user id
+ * and channel id are both bare digits, so posting it unresolved does not fail
+ * loudly. It either 404s or, worse, addresses whatever channel happens to
+ * carry that id.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+const BOT_TOKEN = "discord-bot-token";
+
+const realSecureKeys = await import("../../../security/secure-keys.js");
+mock.module("../../../security/secure-keys.js", () => ({
+  ...realSecureKeys,
+  getSecureKeyResultAsync: async () => ({
+    value: BOT_TOKEN,
+    unreachable: false,
+  }),
+}));
+
+// Pulled in by `send.js`; stubbed so importing the transport does not reach
+// the attachment store. No test here sends an attachment.
+mock.module("../../../persistence/attachments-store.js", () => ({
+  getAttachmentContent: () => null,
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => ({ debug() {}, info() {}, warn() {}, error() {} }),
+}));
+
+const { openDiscordDmChannel, resetDiscordDmChannelCache } =
+  await import("./api.js");
+const { discordTransport } = await import("./transport.js");
+
+const originalFetch = globalThis.fetch;
+
+interface Captured {
+  url: string;
+  method: string;
+  body: unknown;
+}
+
+let calls: Captured[] = [];
+
+/** The user snowflake a notice is addressed to. */
+const RECIPIENT = "900000000000000042";
+/** The DM channel Discord hands back for that recipient. */
+const DM_CHANNEL = "800000000000000099";
+/** The public guild channel the requester was seen in. */
+const GUILD_CHANNEL = "700000000000000001";
+
+/**
+ * Answer the create-DM route with a channel and every other route with a
+ * message. Keyed on the route so a mis-routed call is visible as a wrong
+ * payload rather than quietly succeeding.
+ */
+function stubFetch(): void {
+  globalThis.fetch = (async (url: string | URL, init?: RequestInit) => {
+    const href = String(url);
+    calls.push({
+      url: href,
+      method: init?.method ?? "GET",
+      body: init?.body,
+    });
+    const payload = href.endsWith("/users/@me/channels")
+      ? { id: DM_CHANNEL }
+      : { id: "msg-1" };
+    return new Response(JSON.stringify(payload), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+}
+
+beforeEach(() => {
+  calls = [];
+  resetDiscordDmChannelCache();
+  stubFetch();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("openDiscordDmChannel", () => {
+  test("POSTs the documented create-DM route with recipient_id", async () => {
+    const channelId = await openDiscordDmChannel(RECIPIENT);
+
+    expect(channelId).toBe(DM_CHANNEL);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe("https://discord.com/api/v10/users/@me/channels");
+    expect(calls[0].method).toBe("POST");
+    expect(JSON.parse(String(calls[0].body))).toEqual({
+      recipient_id: RECIPIENT,
+    });
+  });
+
+  test("resolves a repeat recipient without a second API call", async () => {
+    // Discord returns the existing channel rather than opening a second, so
+    // this is not about correctness. It is about the documented rate limit:
+    // a bot that opens DMs too quickly gets blocked from opening new ones,
+    // and a per-notice lane would re-open on every delivery.
+    await openDiscordDmChannel(RECIPIENT);
+    await openDiscordDmChannel(RECIPIENT);
+    await openDiscordDmChannel(RECIPIENT);
+
+    expect(calls).toHaveLength(1);
+  });
+
+  test("concurrent opens for one recipient share a single request", async () => {
+    // The cache cannot help here: nothing has populated it yet. A verification
+    // send and a guardian notice can address the same person in one tick, and
+    // Discord blocks a bot that opens DMs too quickly.
+    const [a, b, c] = await Promise.all([
+      openDiscordDmChannel(RECIPIENT),
+      openDiscordDmChannel(RECIPIENT),
+      openDiscordDmChannel(RECIPIENT),
+    ]);
+
+    expect(calls).toHaveLength(1);
+    expect([a, b, c]).toEqual([DM_CHANNEL, DM_CHANNEL, DM_CHANNEL]);
+  });
+
+  test("a channel-less answer throws, and is not pinned for later callers", async () => {
+    globalThis.fetch = (async () =>
+      new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    await expect(openDiscordDmChannel(RECIPIENT)).rejects.toThrow(
+      /no channel id/i,
+    );
+
+    // A transient failure must not leave every later caller sharing the
+    // rejected promise.
+    stubFetch();
+    await expect(openDiscordDmChannel(RECIPIENT)).resolves.toBe(DM_CHANNEL);
+  });
+
+  test("opens a separate channel per recipient", async () => {
+    await openDiscordDmChannel(RECIPIENT);
+    await openDiscordDmChannel("900000000000000043");
+
+    expect(calls).toHaveLength(2);
+    expect(JSON.parse(String(calls[1].body))).toEqual({
+      recipient_id: "900000000000000043",
+    });
+  });
+
+});
+
+describe("discordTransport with dm=1", () => {
+  test("delivers to the opened DM channel, never to the id it was handed", async () => {
+    await discordTransport.deliver(
+      { callbackUrl: "/deliver/discord?dm=1", params: { dm: "1" } },
+      { chatId: RECIPIENT, text: "Your access request was declined." },
+    );
+
+    const messageCalls = calls.filter((c) => c.url.includes("/messages"));
+    expect(messageCalls).toHaveLength(1);
+    expect(messageCalls[0].url).toBe(
+      `https://discord.com/api/v10/channels/${DM_CHANNEL}/messages`,
+    );
+    // The recipient's own snowflake must never appear as a channel in the
+    // route: that is the unresolved-user-id delivery this lane exists to stop.
+    expect(messageCalls[0].url).not.toContain(RECIPIENT);
+  });
+
+  test("a dm delivery ignores threadId, which addresses a guild thread", async () => {
+    await discordTransport.deliver(
+      {
+        callbackUrl: "/deliver/discord?dm=1",
+        params: { dm: "1", threadId: "700000000000000009" },
+      },
+      { chatId: RECIPIENT, text: "expired" },
+    );
+
+    const messageCalls = calls.filter((c) => c.url.includes("/messages"));
+    expect(messageCalls[0].url).toContain(DM_CHANNEL);
+    expect(messageCalls[0].url).not.toContain("700000000000000009");
+  });
+
+  test("without dm, chatId is still a channel and no DM is opened", async () => {
+    // The ordinary in-channel reply must not start routing through a DM.
+    await discordTransport.deliver(
+      { callbackUrl: "/deliver/discord", params: {} },
+      { chatId: GUILD_CHANNEL, text: "hello" },
+    );
+
+    expect(calls.some((c) => c.url.endsWith("/users/@me/channels"))).toBe(
+      false,
+    );
+    expect(calls[0].url).toBe(
+      `https://discord.com/api/v10/channels/${GUILD_CHANNEL}/messages`,
+    );
+  });
+});