@vellumai/assistant 0.8.2 → 0.8.4

package/src/messaging/providers/a2a/deliver.ts

@@ -0,0 +1,156 @@
+/**
+ * A2A direct delivery adapter.
+ *
+ * Completes an A2A task with response artifacts and optionally POSTs the
+ * completed task to the requester's push notification URL.
+ */
+
+import type {
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+} from "@vellumai/gateway-client";
+
+import {
+  A2A_CONTENT_TYPE,
+  A2A_VERSION,
+  A2A_VERSION_HEADER,
+} from "../../../a2a/protocol-constants.js";
+import type { Part } from "../../../a2a/protocol-types.js";
+import * as taskStore from "../../../a2a/task-store.js";
+import { getLogger } from "../../../util/logger.js";
+import {
+  computeRetryDelay,
+  isRetryableStatus,
+  sleep,
+} from "../../../util/retry.js";
+
+const log = getLogger("a2a-deliver");
+
+const MAX_RETRIES = 3;
+const PUSH_TIMEOUT_MS = 15_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Extract the `taskId` query parameter from a callback URL. */
+function parseTaskId(callbackUrl: string): string | null {
+  try {
+    return new URL(callbackUrl).searchParams.get("taskId");
+  } catch {
+    return null;
+  }
+}
+
+/** Build A2A parts from a channel reply payload. */
+function buildParts(payload: ChannelReplyPayload): Part[] {
+  const parts: Part[] = [];
+
+  if (payload.text) {
+    parts.push({ kind: "text", text: payload.text });
+  }
+
+  if (payload.attachments) {
+    for (const att of payload.attachments) {
+      parts.push({
+        kind: "file",
+        filename: att.filename,
+        media_type: att.mimeType,
+        url: att.data,
+      });
+    }
+  }
+
+  return parts;
+}
+
+/** POST the completed task to the requester's push URL with retry. */
+async function pushNotification(
+  pushUrl: string,
+  taskJson: unknown,
+): Promise<void> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      await sleep(computeRetryDelay(attempt - 1));
+    }
+
+    try {
+      const response = await fetch(pushUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": A2A_CONTENT_TYPE,
+          [A2A_VERSION_HEADER]: A2A_VERSION,
+        },
+        body: JSON.stringify(taskJson),
+        signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
+      });
+
+      if (response.ok) return;
+
+      const body = await response.text().catch(() => "");
+      lastError = new Error(
+        `Push notification failed with status ${response.status}: ${body}`,
+      );
+
+      if (!isRetryableStatus(response.status)) {
+        break;
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+    }
+  }
+
+  // Push failure is logged but doesn't propagate
+  log.warn(
+    { pushUrl, error: lastError?.message },
+    "A2A push notification failed after retries",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Deliver an assistant reply as an A2A task completion. */
+export async function deliverA2AReply(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+): Promise<ChannelDeliveryResult> {
+  const taskId = parseTaskId(callbackUrl);
+  if (!taskId) {
+    return { ok: false };
+  }
+
+  const parts = buildParts(payload);
+  if (parts.length === 0) {
+    log.debug({ taskId }, "No content to deliver; skipping A2A completion");
+    return { ok: true };
+  }
+
+  let completedTask;
+  try {
+    completedTask = taskStore.completeWithArtifacts(taskId, [
+      { artifact_id: crypto.randomUUID(), parts },
+    ]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ taskId, error: message }, "Failed to complete A2A task");
+    return { ok: false };
+  }
+
+  // Push notification — fire-and-forget
+  const pushUrl = taskStore.getPushUrl(taskId);
+  if (pushUrl) {
+    pushNotification(pushUrl, completedTask).catch((err) => {
+      log.error(
+        { taskId, pushUrl, error: String(err) },
+        "Unexpected push notification error",
+      );
+    });
+  }
+
+  log.info({ taskId }, "A2A reply delivered");
+  return { ok: true };
+}

package/src/messaging/providers/gmail/client.ts

@@ -422,13 +422,16 @@ async function executeBatchCall(
 /** Max concurrent individual getMessage requests (matches batch concurrency) */
 const INDIVIDUAL_CONCURRENCY = BATCH_CONCURRENCY;
 
+/** Delay between waves of individual fetches to avoid rate-limit storms (ms). */
+const INTER_WAVE_DELAY_MS = 500;
+
 /**
  * Fetch all messages individually using getMessage (no batch endpoint).
  * Used as a fallback when the batch API is unavailable (e.g. platform connections
  * that cannot expose raw tokens for the multipart batch endpoint).
  *
- * Processes messages in waves of INDIVIDUAL_CONCURRENCY to avoid unbounded
- * parallelism that would trigger 429s on high-volume paths like senderDigest.
+ * Processes messages in waves of INDIVIDUAL_CONCURRENCY with a brief inter-wave
+ * delay to avoid triggering upstream rate limits on high-volume paths.
  */
 async function fetchMessagesIndividually(
   connection: OAuthConnection,
@@ -441,6 +444,10 @@ async function fetchMessagesIndividually(
   const results: GmailMessage[] = [];
   for (let i = 0; i < messageIds.length; i += INDIVIDUAL_CONCURRENCY) {
     signal?.throwIfAborted();
+    // Delay between waves (skip before the first wave)
+    if (i > 0) {
+      await signalAwareSleep(INTER_WAVE_DELAY_MS, signal);
+    }
     const wave = messageIds.slice(i, i + INDIVIDUAL_CONCURRENCY);
     const waveResults = await Promise.all(
       wave.map((id) =>

package/src/messaging/providers/index.ts

@@ -5,7 +5,7 @@
  * matcher and send logic here.  The gateway-client consults
  * `isDirectDelivery()` before falling back to the HTTP proxy path.
  *
- * Currently supported: WhatsApp, Telegram, Slack.
+ * Currently supported: WhatsApp, Telegram, Slack, A2A.
  */
 
 import type {
@@ -15,6 +15,7 @@ import type {
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { getLogger } from "../../util/logger.js";
+import { deliverA2AReply } from "./a2a/deliver.js";
 import {
   sendSlackAssistantThreadStatus,
   sendSlackAttachments,
@@ -59,6 +60,10 @@ function isSlackCallback(callbackUrl: string): boolean {
   }
 }
 
+function isA2ACallback(callbackUrl: string): boolean {
+  return matchesPathname(callbackUrl, "/deliver/a2a");
+}
+
 function parseSlackCallbackParams(callbackUrl: string): {
   channel?: string;
   threadTs?: string;
@@ -169,8 +174,14 @@ async function deliverSlack(
       channel,
       threadTs: statusThreadTs,
       status,
+      loadingMessages,
     } = payload.assistantThreadStatus;
-    await sendSlackAssistantThreadStatus(channel, statusThreadTs, status);
+    await sendSlackAssistantThreadStatus(
+      channel,
+      statusThreadTs,
+      status,
+      loadingMessages,
+    );
     return { ok: true };
   }
 
@@ -233,7 +244,8 @@ export function isDirectDelivery(callbackUrl: string): boolean {
   return (
     isWhatsAppCallback(callbackUrl) ||
     isTelegramCallback(callbackUrl) ||
-    isSlackCallback(callbackUrl)
+    isSlackCallback(callbackUrl) ||
+    isA2ACallback(callbackUrl)
   );
 }
 
@@ -254,6 +266,9 @@ export async function deliverDirect(
   if (isSlackCallback(callbackUrl)) {
     return deliverSlack(callbackUrl, payload);
   }
+  if (isA2ACallback(callbackUrl)) {
+    return deliverA2AReply(callbackUrl, payload);
+  }
 
   // Defensive — isDirectDelivery should have returned false.
   throw new Error(

package/src/messaging/providers/slack/__tests__/adapter-mention-rendering.test.ts

@@ -21,7 +21,7 @@ mock.module("../../../../oauth/oauth-store.js", () => ({
   isProviderConnected: async () => false,
 }));
 
-const findContactChannelMock = mock(() => undefined);
+const findContactChannelMock = mock((): unknown => undefined);
 const upsertContactChannelMock = mock(() => {});
 mock.module("../../../../contacts/contact-store.js", () => ({
   findContactChannel: findContactChannelMock,
@@ -30,9 +30,13 @@ mock.module("../../../../contacts/contacts-write.js", () => ({
   upsertContactChannel: upsertContactChannelMock,
 }));
 
-import { slackProvider } from "../adapter.js";
+import {
+  __resetSlackUserInfoCacheForTests,
+  slackProvider,
+} from "../adapter.js";
 
 const originalFetch = globalThis.fetch;
+let userInfoCalls: string[] = [];
 
 function installFetchStub() {
   globalThis.fetch = (async (
@@ -60,6 +64,73 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
   const method = parsed.pathname.split("/").at(-1);
 
   if (method === "conversations.history") {
+    if (parsed.searchParams.get("channel") === "C_USERINFO_FAIL") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000006.000700",
+            user: "UMISSING",
+            text: "Fallback sender message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_USERINFO_RETRY") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000007.000800",
+            user: "URETRY",
+            text: "Retry sender message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_TIMEZONE_CACHE") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            ts: "1700000004.000500",
+            user: "USENDER",
+            text: "First timezone-bearing message",
+          },
+          {
+            type: "message",
+            ts: "1700000005.000600",
+            user: "USENDER",
+            text: "Second timezone-bearing message",
+          },
+        ],
+      };
+    }
+
+    if (parsed.searchParams.get("channel") === "C_BOT_HISTORY") {
+      return {
+        ok: true,
+        has_more: false,
+        messages: [
+          {
+            type: "message",
+            subtype: "bot_message",
+            ts: "1700000003.000400",
+            bot_id: "B_ASSISTANT",
+            text: "Bot-authored history",
+          },
+        ],
+      };
+    }
+
     return {
       ok: true,
       has_more: false,
@@ -117,7 +188,9 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
   }
 
   if (method === "users.info") {
-    return fakeUserInfoResponse(parsed.searchParams.get("user") ?? "");
+    const userId = parsed.searchParams.get("user") ?? "";
+    userInfoCalls.push(userId);
+    return fakeUserInfoResponse(userId);
   }
 
   return { ok: true };
@@ -141,6 +214,9 @@ function fakeUserInfoResponse(userId: string): Record<string, unknown> {
       user: {
         id: "USENDER",
         name: "sender",
+        tz: "America/New_York",
+        tz_label: "Eastern Time",
+        tz_offset: -18000,
         profile: { display_name: "Sender" },
       },
     };
@@ -157,11 +233,93 @@ function fakeUserInfoResponse(userId: string): Record<string, unknown> {
     };
   }
 
+  if (userId === "URETRY") {
+    const retryCalls = userInfoCalls.filter((call) => call === userId).length;
+    if (retryCalls === 1) {
+      return { ok: false, error: "temporarily_unavailable" };
+    }
+    return {
+      ok: true,
+      user: {
+        id: "URETRY",
+        name: "retry_sender",
+        tz: "America/Chicago",
+        tz_label: "Central Time",
+        tz_offset: -21600,
+        profile: { display_name: "Retry Sender" },
+      },
+    };
+  }
+
   return { ok: false, error: "user_not_found" };
 }
 
+function makeOAuthConnection(
+  id: string,
+  accountInfo: string,
+  displayName: string,
+  timezone: string,
+  timezoneLabel: string,
+  timezoneOffsetSeconds: number,
+): OAuthConnection {
+  return {
+    id,
+    provider: "slack",
+    accountInfo,
+    request: async (req) => {
+      if (req.path === "/conversations.history") {
+        return {
+          status: 200,
+          headers: {},
+          body: {
+            ok: true,
+            has_more: false,
+            messages: [
+              {
+                type: "message",
+                ts: "1700000008.000900",
+                user: "USAME",
+                text: "Account scoped sender",
+              },
+            ],
+          },
+        };
+      }
+      if (req.path === "/users.info") {
+        const userId = req.query?.user;
+        userInfoCalls.push(`${id}:${userId}`);
+        return {
+          status: 200,
+          headers: {},
+          body: {
+            ok: true,
+            user: {
+              id: "USAME",
+              name: displayName.toLowerCase().replaceAll(" ", "_"),
+              tz: timezone,
+              tz_label: timezoneLabel,
+              tz_offset: timezoneOffsetSeconds,
+              profile: { display_name: displayName },
+            },
+          },
+        };
+      }
+      return {
+        status: 200,
+        headers: {},
+        body: { ok: true },
+      };
+    },
+    withToken: async <T>(_fn: (token: string) => Promise<T>): Promise<T> => {
+      throw new Error("withToken was not expected");
+    },
+  };
+}
+
 describe("Slack adapter mention rendering", () => {
   beforeEach(async () => {
+    __resetSlackUserInfoCacheForTests();
+    userInfoCalls = [];
     getSecureKeyAsyncMock.mockReset();
     getSecureKeyAsyncMock.mockImplementation(async (key: string) => {
       if (key === credentialKey("slack_channel", "bot_token")) {
@@ -190,6 +348,174 @@ describe("Slack adapter mention rendering", () => {
     expect(messages[0].reactions).toEqual([{ name: "eyes", count: 1 }]);
   });
 
+  test("getHistory preserves bot ids for bot-authored Slack messages", async () => {
+    const messages = await slackProvider.getHistory(undefined, "C_BOT_HISTORY");
+
+    expect(messages).toHaveLength(1);
+    expect(messages[0].sender).toEqual({ id: "B_ASSISTANT", name: "unknown" });
+    expect(messages[0].metadata).toEqual({
+      isBot: true,
+      slackBotId: "B_ASSISTANT",
+    });
+  });
+
+  test("getHistory caches Slack user info and maps timezone metadata", async () => {
+    const messages = await slackProvider.getHistory(
+      undefined,
+      "C_TIMEZONE_CACHE",
+    );
+
+    expect(messages).toHaveLength(2);
+    expect(userInfoCalls.filter((userId) => userId === "USENDER")).toHaveLength(
+      1,
+    );
+    expect(messages.map((message) => message.sender)).toEqual([
+      { id: "USENDER", name: "Sender" },
+      { id: "USENDER", name: "Sender" },
+    ]);
+    expect(messages.map((message) => message.metadata)).toEqual([
+      {
+        actorTimezone: "America/New_York",
+        actorTimezoneLabel: "Eastern Time",
+        actorTimezoneOffsetSeconds: -18000,
+      },
+      {
+        actorTimezone: "America/New_York",
+        actorTimezoneLabel: "Eastern Time",
+        actorTimezoneOffsetSeconds: -18000,
+      },
+    ]);
+  });
+
+  test("getHistory prefers contact display names while still fetching Slack timezone facts", async () => {
+    findContactChannelMock.mockImplementationOnce(() => ({
+      contact: { displayName: "Saved Sender" },
+    }));
+
+    const messages = await slackProvider.getHistory(
+      undefined,
+      "C_TIMEZONE_CACHE",
+    );
+
+    expect(userInfoCalls.filter((userId) => userId === "USENDER")).toHaveLength(
+      1,
+    );
+    expect(messages[0].sender).toEqual({
+      id: "USENDER",
+      name: "Saved Sender",
+    });
+    expect(messages[0].metadata).toEqual({
+      actorTimezone: "America/New_York",
+      actorTimezoneLabel: "Eastern Time",
+      actorTimezoneOffsetSeconds: -18000,
+    });
+  });
+
+  test("getHistory caches fallback user info for permanent users.info failures", async () => {
+    const firstMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_FAIL",
+    );
+    const secondMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_FAIL",
+    );
+
+    expect(firstMessages).toHaveLength(1);
+    expect(secondMessages).toHaveLength(1);
+    expect(
+      userInfoCalls.filter((userId) => userId === "UMISSING"),
+    ).toHaveLength(1);
+    expect(firstMessages[0].sender).toEqual({
+      id: "UMISSING",
+      name: "UMISSING",
+    });
+    expect(secondMessages[0].sender).toEqual({
+      id: "UMISSING",
+      name: "UMISSING",
+    });
+    expect(firstMessages[0].metadata).toBeUndefined();
+    expect(secondMessages[0].metadata).toBeUndefined();
+  });
+
+  test("getHistory does not cache fallback user info after transient users.info failures", async () => {
+    const firstMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_RETRY",
+    );
+    const secondMessages = await slackProvider.getHistory(
+      undefined,
+      "C_USERINFO_RETRY",
+    );
+
+    expect(userInfoCalls.filter((userId) => userId === "URETRY")).toHaveLength(
+      2,
+    );
+    expect(firstMessages[0].sender).toEqual({
+      id: "URETRY",
+      name: "URETRY",
+    });
+    expect(firstMessages[0].metadata).toBeUndefined();
+    expect(secondMessages[0].sender).toEqual({
+      id: "URETRY",
+      name: "Retry Sender",
+    });
+    expect(secondMessages[0].metadata).toEqual({
+      actorTimezone: "America/Chicago",
+      actorTimezoneLabel: "Central Time",
+      actorTimezoneOffsetSeconds: -21600,
+    });
+  });
+
+  test("getHistory scopes Slack user info cache by OAuth connection", async () => {
+    const workspaceA = makeOAuthConnection(
+      "conn-workspace-a",
+      "workspace-a",
+      "Workspace A Sender",
+      "America/Los_Angeles",
+      "Pacific Time",
+      -28800,
+    );
+    const workspaceB = makeOAuthConnection(
+      "conn-workspace-b",
+      "workspace-b",
+      "Workspace B Sender",
+      "Europe/London",
+      "Greenwich Mean Time",
+      0,
+    );
+
+    const messagesA = await slackProvider.getHistory(
+      workspaceA,
+      "C_ACCOUNT_SCOPE",
+    );
+    const messagesB = await slackProvider.getHistory(
+      workspaceB,
+      "C_ACCOUNT_SCOPE",
+    );
+
+    expect(userInfoCalls).toContain("conn-workspace-a:USAME");
+    expect(userInfoCalls).toContain("conn-workspace-b:USAME");
+    expect(messagesA[0].sender).toEqual({
+      id: "USAME",
+      name: "Workspace A Sender",
+    });
+    expect(messagesA[0].metadata).toEqual({
+      actorTimezone: "America/Los_Angeles",
+      actorTimezoneLabel: "Pacific Time",
+      actorTimezoneOffsetSeconds: -28800,
+    });
+    expect(messagesB[0].sender).toEqual({
+      id: "USAME",
+      name: "Workspace B Sender",
+    });
+    expect(messagesB[0].metadata).toEqual({
+      actorTimezone: "Europe/London",
+      actorTimezoneLabel: "Greenwich Mean Time",
+      actorTimezoneOffsetSeconds: 0,
+    });
+  });
+
   test("getThreadReplies renders Slack user mentions for model-facing text without changing sender identity", async () => {
     const messages = await slackProvider.getThreadReplies!(
       undefined,

package/src/messaging/providers/slack/__tests__/adapter-token-routing.test.ts

@@ -49,7 +49,11 @@ mock.module("../../../../contacts/contacts-write.js", () => ({
   upsertContactChannel: () => {},
 }));
 
-import { slackProvider, withSlackBotToken } from "../adapter.js";
+import {
+  resolveSlackBotUserId,
+  slackProvider,
+  withSlackBotToken,
+} from "../adapter.js";
 
 // ── fetch capture ───────────────────────────────────────────────────────────
 
@@ -104,6 +108,16 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
   if (url.includes("/chat.postMessage")) {
     return { ok: true, ts: "1700000000.000100", channel: "C123" };
   }
+  if (url.includes("/bots.info")) {
+    const botId = new URL(url).searchParams.get("bot");
+    return {
+      ok: true,
+      bot: {
+        id: botId,
+        user_id: botId === "B_ASSISTANT" ? "U_BOT" : "U_OTHER_BOT",
+      },
+    };
+  }
   // Default envelope for any other method the adapter might call.
   return { ok: true };
 }
@@ -319,4 +333,23 @@ describe("Slack adapter token routing", () => {
       account: "workspace-b",
     });
   });
+
+  test("bot id resolver maps Slack bot ids through the bot token", async () => {
+    const resolved = await slackProvider.resolveConnection!();
+    expect(resolved).toBeUndefined();
+
+    const userId = await resolveSlackBotUserId(undefined, "B_ASSISTANT");
+    const repeatedUserId = await resolveSlackBotUserId(
+      undefined,
+      "B_ASSISTANT",
+    );
+
+    expect(userId).toBe("U_BOT");
+    expect(repeatedUserId).toBe("U_BOT");
+    const botsInfoCalls = captured.filter((c) => c.url.includes("/bots.info"));
+    expect(botsInfoCalls).toHaveLength(2);
+    for (const call of botsInfoCalls) {
+      expect(call.authorization).toBe(`Bearer ${BOT_TOKEN}`);
+    }
+  });
 });