@vellumai/assistant 0.10.3-staging.2 → 0.10.4-staging.1

package/src/messaging/providers/index.ts

@@ -1,277 +1,101 @@
 /**
  * Direct channel delivery — bypasses the gateway HTTP proxy.
  *
- * Each channel that supports direct delivery registers its callback-URL
- * matcher and send logic here.  The gateway-client consults
+ * Each channel exposes a `ChannelTransport`; the callback-URL → channel mapping
+ * lives in `callback-routing.ts`. The gateway-client consults
  * `isDirectDelivery()` before falling back to the HTTP proxy path.
  *
- * Currently supported: WhatsApp, Telegram, Slack, A2A.
+ * Supported: Slack, Telegram, WhatsApp, A2A.
  */
 
 import type {
   ChannelDeliveryResult,
   ChannelReplyPayload,
 } from "@vellumai/gateway-client";
-import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
-import { getLogger } from "../../util/logger.js";
-import { deliverA2AReply } from "./a2a/deliver.js";
-import {
-  sendSlackAssistantThreadStatus,
-  sendSlackAttachments,
-  sendSlackReaction,
-  sendSlackReply,
-  sendSlackTypingIndicator,
-} from "./slack/send.js";
-import {
-  sendTelegramAttachments,
-  sendTelegramReply,
-  sendTelegramTypingIndicator,
-} from "./telegram-bot/send.js";
-import { sendWhatsAppAttachments, sendWhatsAppReply } from "./whatsapp/send.js";
+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 { slackTransport } from "./slack/transport.js";
+import { telegramTransport } from "./telegram-bot/transport.js";
+import { whatsappTransport } from "./whatsapp/transport.js";
+
+// Keyed by `DirectDeliveryChannel` so the type checker enforces that the
+// registered transports cover exactly the channels `callback-routing` resolves:
+// add a channel to that set and this object fails to compile until its transport
+// is registered here (and vice versa). No second list to drift against.
+const TRANSPORTS: Record<DirectDeliveryChannel, ChannelTransport> = {
+  slack: slackTransport,
+  telegram: telegramTransport,
+  whatsapp: whatsappTransport,
+  a2a: a2aTransport,
+};
 
-const log = getLogger("direct-delivery");
-
-// ---------------------------------------------------------------------------
-// Callback-URL matchers
-// ---------------------------------------------------------------------------
-
-function matchesPathname(callbackUrl: string, pathname: string): boolean {
-  try {
-    return new URL(callbackUrl).pathname === pathname;
-  } catch {
-    return callbackUrl.endsWith(pathname);
-  }
-}
-
-function isWhatsAppCallback(callbackUrl: string): boolean {
-  return matchesPathname(callbackUrl, "/deliver/whatsapp");
-}
-
-function isTelegramCallback(callbackUrl: string): boolean {
-  return matchesPathname(callbackUrl, "/deliver/telegram");
-}
-
-function isSlackCallback(callbackUrl: string): boolean {
-  try {
-    return new URL(callbackUrl).pathname === "/deliver/slack";
-  } catch {
-    return callbackUrl.endsWith("/deliver/slack");
-  }
-}
-
-function isA2ACallback(callbackUrl: string): boolean {
-  return matchesPathname(callbackUrl, "/deliver/a2a");
+/**
+ * Resolve the transport that owns a gateway callback URL, or `undefined` when
+ * no channel delivers it directly.
+ */
+export function getTransportForCallback(
+  callbackUrl: string,
+): ChannelTransport | undefined {
+  const channel = channelForCallback(callbackUrl);
+  return channel ? TRANSPORTS[channel] : undefined;
 }
 
-function parseSlackCallbackParams(callbackUrl: string): {
-  channel?: string;
-  threadTs?: string;
-  messageTs?: string;
-} {
+function callbackContext(callbackUrl: string): CallbackContext {
+  const params: Record<string, string> = {};
   try {
-    const url = new URL(callbackUrl);
-    return {
-      channel: url.searchParams.get("channel") ?? undefined,
-      threadTs: url.searchParams.get("threadTs") ?? undefined,
-      messageTs: url.searchParams.get("messageTs") ?? undefined,
-    };
-  } catch {
-    return {};
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Per-channel direct delivery
-// ---------------------------------------------------------------------------
-
-async function deliverWhatsApp(
-  payload: ChannelReplyPayload,
-): Promise<ChannelDeliveryResult> {
-  const { chatId, text, attachments, approval } = payload;
-
-  if (text) {
-    await sendWhatsAppReply(chatId, text, approval);
-  } else if (approval) {
-    await sendWhatsAppReply(
-      chatId,
-      approval.plainTextFallback || "Approval required",
-      approval,
-    );
-  }
-
-  if (attachments && attachments.length > 0) {
-    const result = await sendWhatsAppAttachments(chatId, attachments);
-    if (result.allFailed && !text) {
-      throw new ChannelDeliveryError(
-        502,
-        `All ${result.failureCount} attachments failed to deliver`,
-      );
-    }
-  }
-
-  log.info({ chatId, hasText: !!text }, "WhatsApp reply delivered (direct)");
-  return { ok: true };
-}
-
-async function deliverTelegram(
-  payload: ChannelReplyPayload,
-): Promise<ChannelDeliveryResult> {
-  const { chatId, text, attachments, approval, chatAction } = payload;
-
-  if (chatAction === "typing") {
-    await sendTelegramTypingIndicator(chatId);
-    log.debug({ chatId }, "Telegram typing indicator delivered (direct)");
-    return { ok: true };
-  }
-
-  if (text) {
-    await sendTelegramReply(chatId, text, approval);
-  } else if (approval) {
-    await sendTelegramReply(
-      chatId,
-      approval.plainTextFallback || "Approval required",
-      approval,
-    );
-  }
-
-  if (attachments && attachments.length > 0) {
-    const result = await sendTelegramAttachments(chatId, attachments);
-    if (result.allFailed && !text) {
-      throw new ChannelDeliveryError(
-        502,
-        `All ${result.failureCount} attachments failed to deliver`,
-      );
-    }
-  }
-
-  log.info({ chatId, hasText: !!text }, "Telegram reply delivered (direct)");
-  return { ok: true };
-}
-
-async function deliverSlack(
-  callbackUrl: string,
-  payload: ChannelReplyPayload,
-): Promise<ChannelDeliveryResult> {
-  const { chatId, text, attachments, chatAction, blocks } = payload;
-  const params = parseSlackCallbackParams(callbackUrl);
-  const threadTs = params.threadTs;
-
-  // Emoji reaction
-  if (payload.reaction) {
-    await sendSlackReaction(
-      chatId,
-      payload.reaction.name,
-      payload.reaction.messageTs,
-      payload.reaction.action,
-    );
-    return { ok: true };
-  }
-
-  // Assistants API thread status
-  if (payload.assistantThreadStatus) {
-    const {
-      channel,
-      threadTs: statusThreadTs,
-      status,
-      loadingMessages,
-    } = payload.assistantThreadStatus;
-    await sendSlackAssistantThreadStatus(
-      channel,
-      statusThreadTs,
-      status,
-      loadingMessages,
-    );
-    return { ok: true };
-  }
-
-  // Typing indicator
-  if (chatAction === "typing") {
-    const placeholderTs = await sendSlackTypingIndicator(chatId, threadTs);
-    log.debug({ chatId }, "Slack typing indicator delivered (direct)");
-    return { ok: true, ts: placeholderTs };
-  }
-
-  // Text + blocks delivery
-  let sentTs: string | undefined;
-  if (text) {
-    const result = await sendSlackReply(chatId, text, {
-      threadTs,
-      blocks,
-      approval: payload.approval,
-      useBlocks: payload.useBlocks,
-      ephemeral: payload.ephemeral,
-      user: payload.user,
-      messageTs: payload.messageTs,
-    });
-    sentTs = result.ts;
-  } else if (payload.approval) {
-    const result = await sendSlackReply(
-      chatId,
-      payload.approval.plainTextFallback || "Approval required",
-      {
-        threadTs,
-        approval: payload.approval,
-      },
-    );
-    sentTs = result.ts;
-  }
-
-  // Attachments
-  if (attachments && attachments.length > 0) {
-    const result = await sendSlackAttachments(chatId, attachments, threadTs);
-    if (result.allFailed && !text) {
-      throw new ChannelDeliveryError(
-        502,
-        `All ${result.failureCount} attachments failed to deliver`,
-      );
+    // Resolve against a dummy base so base-less callbacks (e.g.
+    // `/deliver/slack?threadTs=…`) still expose their params. `channelForCallback`
+    // already routes those as direct delivery, so dispatch must not drop
+    // threadTs/taskId for them.
+    const url = new URL(callbackUrl, "http://callback.invalid");
+    for (const [key, value] of url.searchParams) {
+      params[key] = value;
     }
+  } catch {
+    // Unparseable callback URL — deliver with no params.
   }
-
-  log.info({ chatId, hasText: !!text }, "Slack reply delivered (direct)");
-  return { ok: true, ts: sentTs };
+  return { callbackUrl, params };
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
- * Returns true when the given callback URL targets a channel whose
- * outbound delivery is handled directly by the assistant (no gateway hop).
+ * True when the callback URL targets a channel whose outbound delivery the
+ * assistant handles directly (no gateway hop).
  */
 export function isDirectDelivery(callbackUrl: string): boolean {
-  return (
-    isWhatsAppCallback(callbackUrl) ||
-    isTelegramCallback(callbackUrl) ||
-    isSlackCallback(callbackUrl) ||
-    isA2ACallback(callbackUrl)
-  );
+  return getTransportForCallback(callbackUrl) !== undefined;
 }
 
 /**
- * Deliver a channel reply directly to the provider API, bypassing the
- * gateway HTTP proxy.  Callers MUST check `isDirectDelivery()` first.
+ * Deliver a channel reply directly to the provider API, bypassing the gateway
+ * HTTP proxy. Callers MUST check `isDirectDelivery()` first.
+ *
+ * Sub-operations (reaction, thread status, typing) route to the transport's
+ * optional method when both the payload field and the method are present;
+ * otherwise the reply is delivered as text / approval / attachments.
  */
 export async function deliverDirect(
   callbackUrl: string,
   payload: ChannelReplyPayload,
 ): Promise<ChannelDeliveryResult> {
-  if (isWhatsAppCallback(callbackUrl)) {
-    return deliverWhatsApp(payload);
+  const transport = getTransportForCallback(callbackUrl);
+  if (!transport) {
+    throw new Error(
+      `deliverDirect called for unsupported callback: ${callbackUrl}`,
+    );
   }
-  if (isTelegramCallback(callbackUrl)) {
-    return deliverTelegram(payload);
+
+  const ctx = callbackContext(callbackUrl);
+  if (payload.reaction && transport.sendReaction) {
+    return transport.sendReaction(ctx, payload);
   }
-  if (isSlackCallback(callbackUrl)) {
-    return deliverSlack(callbackUrl, payload);
+  if (payload.assistantThreadStatus && transport.setThreadStatus) {
+    return transport.setThreadStatus(ctx, payload);
   }
-  if (isA2ACallback(callbackUrl)) {
-    return deliverA2AReply(callbackUrl, payload);
+  if (payload.chatAction === "typing" && transport.sendTyping) {
+    return transport.sendTyping(ctx, payload);
   }
-
-  // Defensive — isDirectDelivery should have returned false.
-  throw new Error(
-    `deliverDirect called for unsupported callback: ${callbackUrl}`,
-  );
+  return transport.deliver(ctx, payload);
 }

package/src/messaging/providers/slack/binding-metadata.ts

@@ -0,0 +1,62 @@
+import { getConfig } from "../../../config/loader.js";
+import type { ExternalConversationBinding } from "../../../memory/external-conversation-store.js";
+import type { ChannelBindingMetadata } from "../../channel-binding-schema.js";
+import {
+  buildSlackMessageDeepLinks,
+  buildSlackWebChannelUrl,
+} from "./deep-link.js";
+
+/**
+ * Slack's contribution to a serialized conversation channel binding: a
+ * human-readable channel name (falling back to the channel id) plus deep
+ * links that jump back to the source thread and channel in the Slack app or
+ * web client.
+ *
+ * The return type is derived from the channel-binding Zod schema
+ * (`ChannelBindingMetadata`) — the single source of truth that also drives
+ * `openapi.yaml` and the web client's generated types — so this builder cannot
+ * drift from the wire contract. Slack is the only channel that can currently
+ * produce message-level deep links, because the link inputs (workspace team
+ * id/url + a stable per-message timestamp) only exist for Slack.
+ */
+export function buildSlackBindingMetadata(
+  binding: ExternalConversationBinding,
+): ChannelBindingMetadata {
+  const externalChatName =
+    binding.externalChatName?.trim() || binding.externalChatId;
+  const slackConfig = getConfig().slack;
+
+  const threadLink =
+    slackConfig && binding.externalThreadId
+      ? buildSlackMessageDeepLinks({
+          teamId: slackConfig.teamId,
+          teamUrl: slackConfig.teamUrl,
+          channelId: binding.externalChatId,
+          messageTs: binding.externalThreadId,
+        })
+      : undefined;
+  const slackThread = binding.externalThreadId
+    ? {
+        channelId: binding.externalChatId,
+        threadTs: binding.externalThreadId,
+        ...(threadLink ? { link: threadLink } : {}),
+      }
+    : undefined;
+
+  const channelWebUrl = slackConfig
+    ? buildSlackWebChannelUrl({
+        teamUrl: slackConfig.teamUrl,
+        channelId: binding.externalChatId,
+      })
+    : undefined;
+
+  return {
+    externalChatName,
+    ...(slackThread ? { slackThread } : {}),
+    slackChannel: {
+      channelId: binding.externalChatId,
+      name: externalChatName,
+      ...(channelWebUrl ? { link: { webUrl: channelWebUrl } } : {}),
+    },
+  };
+}

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

@@ -0,0 +1,92 @@
+import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
+
+import { getLogger } from "../../../util/logger.js";
+import type { ChannelTransport } from "../channel-transport.js";
+import {
+  sendSlackAssistantThreadStatus,
+  sendSlackAttachments,
+  sendSlackReaction,
+  sendSlackReply,
+  sendSlackTypingIndicator,
+} from "./send.js";
+
+const log = getLogger("slack-transport");
+
+export const slackTransport: ChannelTransport = {
+  channel: "slack",
+
+  async deliver(ctx, payload) {
+    const { chatId, text, attachments, blocks } = payload;
+    const threadTs = ctx.params.threadTs;
+
+    let sentTs: string | undefined;
+    if (text) {
+      const result = await sendSlackReply(chatId, text, {
+        threadTs,
+        blocks,
+        approval: payload.approval,
+        useBlocks: payload.useBlocks,
+        ephemeral: payload.ephemeral,
+        user: payload.user,
+        messageTs: payload.messageTs,
+      });
+      sentTs = result.ts;
+    } else if (payload.approval) {
+      const result = await sendSlackReply(
+        chatId,
+        payload.approval.plainTextFallback || "Approval required",
+        { threadTs, approval: payload.approval },
+      );
+      sentTs = result.ts;
+    }
+
+    if (attachments && attachments.length > 0) {
+      const result = await sendSlackAttachments(chatId, attachments, threadTs);
+      if (result.allFailed && !text) {
+        throw new ChannelDeliveryError(
+          502,
+          `All ${result.failureCount} attachments failed to deliver`,
+        );
+      }
+    }
+
+    log.info({ chatId, hasText: !!text }, "Slack reply delivered (direct)");
+    return { ok: true, ts: sentTs };
+  },
+
+  async sendTyping(ctx, payload) {
+    const placeholderTs = await sendSlackTypingIndicator(
+      payload.chatId,
+      ctx.params.threadTs,
+    );
+    log.debug(
+      { chatId: payload.chatId },
+      "Slack typing indicator delivered (direct)",
+    );
+    return { ok: true, ts: placeholderTs };
+  },
+
+  async sendReaction(_ctx, payload) {
+    const reaction = payload.reaction;
+    if (!reaction) return { ok: true };
+    await sendSlackReaction(
+      payload.chatId,
+      reaction.name,
+      reaction.messageTs,
+      reaction.action,
+    );
+    return { ok: true };
+  },
+
+  async setThreadStatus(_ctx, payload) {
+    const status = payload.assistantThreadStatus;
+    if (!status) return { ok: true };
+    await sendSlackAssistantThreadStatus(
+      status.channel,
+      status.threadTs,
+      status.status,
+      status.loadingMessages,
+    );
+    return { ok: true };
+  },
+};

package/src/messaging/providers/telegram-bot/transport.ts

@@ -0,0 +1,51 @@
+import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
+
+import { getLogger } from "../../../util/logger.js";
+import type { ChannelTransport } from "../channel-transport.js";
+import {
+  sendTelegramAttachments,
+  sendTelegramReply,
+  sendTelegramTypingIndicator,
+} from "./send.js";
+
+const log = getLogger("telegram-transport");
+
+export const telegramTransport: ChannelTransport = {
+  channel: "telegram",
+
+  async deliver(_ctx, payload) {
+    const { chatId, text, attachments, approval } = payload;
+
+    if (text) {
+      await sendTelegramReply(chatId, text, approval);
+    } else if (approval) {
+      await sendTelegramReply(
+        chatId,
+        approval.plainTextFallback || "Approval required",
+        approval,
+      );
+    }
+
+    if (attachments && attachments.length > 0) {
+      const result = await sendTelegramAttachments(chatId, attachments);
+      if (result.allFailed && !text) {
+        throw new ChannelDeliveryError(
+          502,
+          `All ${result.failureCount} attachments failed to deliver`,
+        );
+      }
+    }
+
+    log.info({ chatId, hasText: !!text }, "Telegram reply delivered (direct)");
+    return { ok: true };
+  },
+
+  async sendTyping(_ctx, payload) {
+    await sendTelegramTypingIndicator(payload.chatId);
+    log.debug(
+      { chatId: payload.chatId },
+      "Telegram typing indicator delivered (direct)",
+    );
+    return { ok: true };
+  },
+};

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

@@ -0,0 +1,38 @@
+import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
+
+import { getLogger } from "../../../util/logger.js";
+import type { ChannelTransport } from "../channel-transport.js";
+import { sendWhatsAppAttachments, sendWhatsAppReply } from "./send.js";
+
+const log = getLogger("whatsapp-transport");
+
+export const whatsappTransport: ChannelTransport = {
+  channel: "whatsapp",
+
+  async deliver(_ctx, payload) {
+    const { chatId, text, attachments, approval } = payload;
+
+    if (text) {
+      await sendWhatsAppReply(chatId, text, approval);
+    } else if (approval) {
+      await sendWhatsAppReply(
+        chatId,
+        approval.plainTextFallback || "Approval required",
+        approval,
+      );
+    }
+
+    if (attachments && attachments.length > 0) {
+      const result = await sendWhatsAppAttachments(chatId, attachments);
+      if (result.allFailed && !text) {
+        throw new ChannelDeliveryError(
+          502,
+          `All ${result.failureCount} attachments failed to deliver`,
+        );
+      }
+    }
+
+    log.info({ chatId, hasText: !!text }, "WhatsApp reply delivered (direct)");
+    return { ok: true };
+  },
+};

package/src/notifications/__tests__/broadcaster.test.ts

@@ -37,14 +37,6 @@ mock.module("../../contacts/guardian-delivery-reader.js", () => ({
   getGuardianDelivery: async () => null,
 }));
 
-// Use the real destination-resolver (DB-free via the local-read stub below)
-// so this mock does not leak into destination-resolver.test.ts under a shared
-// bun-test invocation. With no guardian, the resolver still yields a vellum
-// destination, which is all these tests exercise.
-mock.module("../../contacts/contact-store.js", () => ({
-  findGuardianForChannel: () => null,
-}));
-
 mock.module("../conversation-pairing.js", () => ({
   pairDeliveryWithConversation: async () => ({
     conversationId: undefined,