@vellumai/assistant 0.8.1 → 0.8.3

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;
@@ -233,7 +238,8 @@ export function isDirectDelivery(callbackUrl: string): boolean {
   return (
     isWhatsAppCallback(callbackUrl) ||
     isTelegramCallback(callbackUrl) ||
-    isSlackCallback(callbackUrl)
+    isSlackCallback(callbackUrl) ||
+    isA2ACallback(callbackUrl)
   );
 }
 
@@ -254,6 +260,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-token-routing.test.ts

@@ -24,13 +24,18 @@ mock.module("../../../../security/secure-keys.js", () => ({
 }));
 
 // OAuth helpers are exercised only when no bot_token is cached. The adapter
-// imports them at module load — route them through a stub that signals any
-// OAuth fallback with a distinctive error so tests can assert on it.
+// imports them at module load, so route them through a configurable stub.
 const OAUTH_FALLBACK_SENTINEL = "OAUTH_FALLBACK_NOT_STUBBED";
-mock.module("../../../../oauth/connection-resolver.js", () => ({
-  resolveOAuthConnection: async (): Promise<OAuthConnection> => {
+const resolveOAuthConnectionMock = mock(
+  async (
+    _provider: string,
+    _opts?: { account?: string },
+  ): Promise<OAuthConnection> => {
     throw new Error(OAUTH_FALLBACK_SENTINEL);
   },
+);
+mock.module("../../../../oauth/connection-resolver.js", () => ({
+  resolveOAuthConnection: resolveOAuthConnectionMock,
 }));
 mock.module("../../../../oauth/oauth-store.js", () => ({
   isProviderConnected: async () => false,
@@ -44,7 +49,7 @@ mock.module("../../../../contacts/contacts-write.js", () => ({
   upsertContactChannel: () => {},
 }));
 
-import { slackProvider } from "../adapter.js";
+import { slackProvider, withSlackBotToken } from "../adapter.js";
 
 // ── fetch capture ───────────────────────────────────────────────────────────
 
@@ -108,9 +113,23 @@ function fakeSlackResponse(url: string): Record<string, unknown> {
 const BOT_TOKEN = "xoxb-BOT";
 const USER_TOKEN = "xoxp-USER";
 
+function makeOAuthConnection(account: string, token: string): OAuthConnection {
+  return {
+    id: `conn-${account}`,
+    provider: "slack",
+    accountInfo: account,
+    request: async () => ({ status: 200, headers: {}, body: { ok: true } }),
+    withToken: async <T>(fn: (rawToken: string) => Promise<T>) => fn(token),
+  };
+}
+
 describe("Slack adapter token routing", () => {
   beforeEach(() => {
     captured.length = 0;
+    resolveOAuthConnectionMock.mockReset();
+    resolveOAuthConnectionMock.mockImplementation(async () => {
+      throw new Error(OAUTH_FALLBACK_SENTINEL);
+    });
     getSecureKeyAsyncMock.mockReset();
     getSecureKeyAsyncMock.mockImplementation(async (key: string) => {
       if (key === credentialKey("slack_channel", "bot_token")) return BOT_TOKEN;
@@ -279,4 +298,25 @@ describe("Slack adapter token routing", () => {
       OAUTH_FALLBACK_SENTINEL,
     );
   });
+
+  test("raw bot token helper resolves the requested OAuth account even when cache is warm", async () => {
+    getSecureKeyAsyncMock.mockImplementation(async () => null);
+    resolveOAuthConnectionMock.mockImplementation(
+      async (_provider: string, opts?: { account?: string }) => {
+        const account = opts?.account ?? "default";
+        return makeOAuthConnection(account, `token-${account}`);
+      },
+    );
+
+    await slackProvider.resolveConnection!("workspace-a");
+
+    const result = await withSlackBotToken("workspace-b", async (token) => {
+      return token;
+    });
+
+    expect(result).toBe("token-workspace-b");
+    expect(resolveOAuthConnectionMock).toHaveBeenCalledWith("slack", {
+      account: "workspace-b",
+    });
+  });
 });

package/src/messaging/providers/slack/__tests__/download.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Unit tests for the assistant-side Slack file downloader used by the
+ * thread-backfill image-hydration path.
+ *
+ * The downloader has three contract-level behaviors worth pinning:
+ *  1. URL selection — `url_private_download` is preferred over `url_private`.
+ *  2. Bearer auth — the bot token MUST be sent on the initial request.
+ *  3. Manual cross-origin redirect handling — the CDN URL is signed and the
+ *     Authorization header MUST NOT be re-sent on the second hop (Slack
+ *     rejects the signed URL when an unexpected Authorization is present).
+ *  4. Returns null when no usable URL is present.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import { downloadSlackFile } from "../download.js";
+
+interface CapturedFetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+let calls: CapturedFetchCall[];
+let responses: Response[];
+let originalFetch: typeof fetch;
+
+beforeEach(() => {
+  calls = [];
+  responses = [];
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({
+      url: typeof input === "string" ? input : input.toString(),
+      init,
+    });
+    const next = responses.shift();
+    if (!next) {
+      throw new Error("downloadSlackFile test: no canned response available");
+    }
+    return next;
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("downloadSlackFile", () => {
+  test("returns null when neither url_private_download nor url_private is present", async () => {
+    const result = await downloadSlackFile(
+      { name: "screenshot.png", mimetype: "image/png" },
+      "xoxb-test",
+    );
+    expect(result).toBeNull();
+    expect(calls.length).toBe(0);
+  });
+
+  test("prefers url_private_download over url_private", async () => {
+    responses.push(
+      new Response(new Uint8Array([1, 2, 3]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    await downloadSlackFile(
+      {
+        id: "F1",
+        name: "shot.png",
+        mimetype: "image/png",
+        urlPrivateDownload: "https://files.slack.com/files-pri/T/F1/download",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test",
+    );
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe(
+      "https://files.slack.com/files-pri/T/F1/download",
+    );
+  });
+
+  test("sends bot token as Bearer on the initial request and base64-encodes the body", async () => {
+    responses.push(
+      new Response(new Uint8Array([0xde, 0xad, 0xbe, 0xef]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "shot.png",
+        mimetype: "image/png",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test-token",
+    );
+    expect(calls.length).toBe(1);
+    const auth = (calls[0].init?.headers as Record<string, string>)
+      ?.Authorization;
+    expect(auth).toBe("Bearer xoxb-test-token");
+    expect(calls[0].init?.redirect).toBe("manual");
+    expect(result).not.toBeNull();
+    expect(result?.filename).toBe("shot.png");
+    expect(result?.mimeType).toBe("image/png");
+    // 0xdeadbeef → "3q2+7w==" in base64.
+    expect(result?.data).toBe("3q2+7w==");
+  });
+
+  test("follows a 302 to the signed CDN URL without re-sending the bearer token", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: {
+          Location:
+            "https://files-edge.slack.com/files-tmb/T-F1-abc/cdn-signed?t=1700000000",
+        },
+      }),
+    );
+    responses.push(
+      new Response(new Uint8Array([1, 2]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/jpeg" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "photo.jpg",
+        mimetype: "image/jpeg",
+        urlPrivateDownload: "https://files.slack.com/files-pri/T/F1/download",
+      },
+      "xoxb-test",
+    );
+    expect(calls.length).toBe(2);
+    expect(calls[0].init?.redirect).toBe("manual");
+    const secondAuth = (calls[1].init?.headers as Record<string, string>)
+      ?.Authorization;
+    expect(secondAuth).toBeUndefined();
+    expect(calls[1].url).toBe(
+      "https://files-edge.slack.com/files-tmb/T-F1-abc/cdn-signed?t=1700000000",
+    );
+    expect(result?.data).toBe(Buffer.from([1, 2]).toString("base64"));
+  });
+
+  test("resolves a relative Location header against the original URL", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: { Location: "/files-tmb/cdn-signed?t=1700" },
+      }),
+    );
+    responses.push(
+      new Response(new Uint8Array([9]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/png" },
+      }),
+    );
+    await downloadSlackFile(
+      {
+        id: "F1",
+        name: "x.png",
+        urlPrivateDownload: "https://files.slack.com/a/b/download",
+      },
+      "xoxb-test",
+    );
+    expect(calls[1].url).toBe(
+      "https://files.slack.com/files-tmb/cdn-signed?t=1700",
+    );
+  });
+
+  test("throws when the second hop responds non-2xx", async () => {
+    responses.push(
+      new Response(null, {
+        status: 302,
+        headers: { Location: "https://files-edge.slack.com/cdn?t=1" },
+      }),
+    );
+    responses.push(
+      new Response(null, { status: 403, statusText: "Forbidden" }),
+    );
+    await expect(
+      downloadSlackFile(
+        {
+          id: "F1",
+          name: "x.png",
+          urlPrivateDownload: "https://files.slack.com/a/b/download",
+        },
+        "xoxb-test",
+      ),
+    ).rejects.toThrow(/403/);
+  });
+
+  test("throws when a redirect has no Location header", async () => {
+    responses.push(new Response(null, { status: 302 }));
+    await expect(
+      downloadSlackFile(
+        {
+          id: "F1",
+          name: "x.png",
+          urlPrivateDownload: "https://files.slack.com/a/b/download",
+        },
+        "xoxb-test",
+      ),
+    ).rejects.toThrow(/no Location header/);
+  });
+
+  test("falls back to response Content-Type when file.mimetype is absent", async () => {
+    responses.push(
+      new Response(new Uint8Array([1]).buffer, {
+        status: 200,
+        headers: { "Content-Type": "image/webp; charset=binary" },
+      }),
+    );
+    const result = await downloadSlackFile(
+      {
+        id: "F1",
+        name: "photo.webp",
+        urlPrivate: "https://files.slack.com/files-pri/T/F1/inline",
+      },
+      "xoxb-test",
+    );
+    expect(result?.mimeType).toBe("image/webp");
+  });
+});

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

@@ -99,6 +99,30 @@ function getWriteAuth(connection?: OAuthConnection): OAuthConnection | string {
   return getSlackAuth(connection);
 }
 
+/**
+ * Resolve the bot token (raw string) and pass it to `fn`. Returns the
+ * callback's result, or `null` when no Slack auth is available.
+ *
+ * Bridges the Socket Mode case (cached string token) and the OAuth case
+ * (`OAuthConnection.withToken`) for callers that need a raw token to hand
+ * to a non-Slack-client API call — currently `downloadSlackFile` for inline
+ * file/image fetches. Slack-client method calls should keep going through
+ * `getReadAuth` / `getWriteAuth` and pass the union through.
+ */
+export async function withSlackBotToken<T>(
+  account: string | undefined,
+  fn: (token: string) => Promise<T>,
+): Promise<T | null> {
+  // Resolve for this call's account even when the process cache is warm.
+  // Multi-workspace backfills can interleave, so use the returned connection
+  // directly instead of accepting any previously cached workspace token.
+  const resolvedAuth = await slackProvider.resolveConnection?.(account);
+  const auth = resolvedAuth ?? _cachedSlackWriteAuth;
+  if (!auth) return null;
+  if (typeof auth === "string") return fn(auth);
+  return auth.withToken(fn);
+}
+
 /**
  * Run a read-path Slack call, falling back to the bot token if the cached
  * user token is rejected with an auth error. On fallback, the read cache is
@@ -192,15 +216,31 @@ function mapConversation(conv: SlackConversation): Conversation {
   };
 }
 
-function mapSlackFiles(
-  files: SlackMessage["files"],
-): Array<{ id?: string; name: string; mimetype?: string }> | undefined {
+function mapSlackFiles(files: SlackMessage["files"]):
+  | Array<{
+      id?: string;
+      name: string;
+      mimetype?: string;
+      /**
+       * Transient — only present on the in-flight `ProviderMessage.metadata`.
+       * The persisted `slackFiles` shape carries `{ id, name, mimetype }` only
+       * (see `slackFileMetadataSchema`). Callers that hydrate image attachments
+       * during backfill rely on this URL; persistence strips it before write.
+       */
+      urlPrivateDownload?: string;
+      urlPrivate?: string;
+    }>
+  | undefined {
   if (!files || files.length === 0) return undefined;
   const mapped = files
     .map((file) => ({
       ...(file.id ? { id: file.id } : {}),
       name: file.name,
       ...(file.mimetype ? { mimetype: file.mimetype } : {}),
+      ...(file.url_private_download
+        ? { urlPrivateDownload: file.url_private_download }
+        : {}),
+      ...(file.url_private ? { urlPrivate: file.url_private } : {}),
     }))
     .filter((file) => file.name.length > 0);
   return mapped.length > 0 ? mapped : undefined;
@@ -419,8 +459,6 @@ export const slackProvider: MessagingProvider = {
       if (conv.type === "dm" && conv.metadata?.dmUserId) {
         const dmUserId = conv.metadata.dmUserId as string;
         conv.name = await resolveUserName(auth, dmUserId);
-
-
       }
     }
 

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

@@ -20,8 +20,10 @@ import type {
   SlackConversationsListResponse,
   SlackConversationsOpenResponse,
   SlackPostMessageResponse,
+  SlackReactionsAddResponse,
   SlackSearchMessagesResponse,
   SlackUserInfoResponse,
+  SlackUsersListResponse,
 } from "./types.js";
 
 const SLACK_API_BASE = "https://slack.com/api";
@@ -432,3 +434,28 @@ export async function searchMessages(
     },
   );
 }
+
+export async function addReaction(
+  connectionOrToken: OAuthConnection | string,
+  channel: string,
+  timestamp: string,
+  name: string,
+): Promise<SlackReactionsAddResponse> {
+  return request<SlackReactionsAddResponse>(
+    connectionOrToken,
+    "reactions.add",
+    undefined,
+    { channel, timestamp, name },
+  );
+}
+
+export async function listUsers(
+  connectionOrToken: OAuthConnection | string,
+  limit = 200,
+  cursor?: string,
+): Promise<SlackUsersListResponse> {
+  return request<SlackUsersListResponse>(connectionOrToken, "users.list", {
+    limit: String(limit),
+    cursor,
+  });
+}