@vellumai/vellum-gateway 0.8.2 → 0.8.4

package/src/runtime/client.ts

@@ -503,15 +503,58 @@ export type TwilioForwardResponse = {
  * to Twilio, keeping the signing key out of the daemon for this flow.
  */
 const TWILIO_RELAY_TOKEN_PLACEHOLDER = "__VELLUM_RELAY_TOKEN__";
+const PLATFORM_CALLBACK_MARKER = "/gateway/callbacks/";
+
+function toWebSocketBaseUrl(url: string): string {
+  return url.replace(/^http(s?)/, "ws$1");
+}
+
+function extractPlatformCallbackAssistantId(
+  value: unknown,
+): string | undefined {
+  const normalized = normalizePublicBaseUrl(value);
+  if (!normalized) return undefined;
+
+  let pathname: string;
+  try {
+    pathname = new URL(normalized).pathname;
+  } catch {
+    return undefined;
+  }
+
+  const markerIndex = pathname.indexOf(PLATFORM_CALLBACK_MARKER);
+  if (markerIndex === -1) return undefined;
+
+  const assistantIdStart = markerIndex + PLATFORM_CALLBACK_MARKER.length;
+  const assistantId = pathname.slice(assistantIdStart).split("/")[0]?.trim();
+  return assistantId || undefined;
+}
+
+function resolveVelayBaseWssUrl(
+  config: GatewayConfig,
+  platformAssistantId?: string,
+): string | undefined {
+  if (!config.velayBaseUrl || !platformAssistantId) return undefined;
+
+  const withPath =
+    config.velayBaseUrl.replace(/\/+$/, "") + "/" + platformAssistantId;
+  const normalizedVelayUrl = normalizePublicBaseUrl(withPath);
+  return normalizedVelayUrl
+    ? toWebSocketBaseUrl(normalizedVelayUrl)
+    : undefined;
+}
 
 /**
  * Resolve the public base URL as a WebSocket URL (`wss://…`).
  *
  * Sources (in priority order):
- * 1. `ingress.publicBaseUrl` from the config file — written by Velay
- *    after tunnel registration, or set manually for self-hosted.
- * 2. `VELAY_BASE_URL` + platform assistant ID — fallback for platform
- *    sidecars before the config cache has observed the registered URL.
+ * 1. `VELAY_BASE_URL` + the assistant ID from the signed platform callback
+ *    URL.
+ * 2. `ingress.publicBaseUrl` from the config file when it is a real public
+ *    gateway base URL — written by Velay after tunnel registration, or set
+ *    manually for self-hosted.
+ * 3. `VELAY_BASE_URL` + the platform assistant ID from a configured callback
+ *    URL or credential cache.
  *
  * Returns `undefined` when no source provides a value — the placeholder
  * will remain in TwiML and Twilio will fail to connect, which is the
@@ -521,20 +564,29 @@ export function resolvePublicBaseWssUrl(
   config: GatewayConfig,
   configFile?: ConfigFileCache,
   platformAssistantId?: string,
+  validatedPublicUrl?: string,
 ): string | undefined {
   const raw = configFile?.getString("ingress", "publicBaseUrl");
   const normalized = normalizePublicBaseUrl(raw);
-  if (normalized) return normalized.replace(/^http(s?)/, "ws$1");
-
-  if (config.velayBaseUrl && platformAssistantId) {
-    const withPath =
-      config.velayBaseUrl.replace(/\/+$/, "") + "/" + platformAssistantId;
-    const normalizedVelayUrl = normalizePublicBaseUrl(withPath);
-    if (normalizedVelayUrl) {
-      return normalizedVelayUrl.replace(/^http(s?)/, "ws$1");
-    }
+
+  const validatedCallbackAssistantId =
+    extractPlatformCallbackAssistantId(validatedPublicUrl);
+  const validatedCallbackWssUrl = resolveVelayBaseWssUrl(
+    config,
+    validatedCallbackAssistantId,
+  );
+  if (validatedCallbackWssUrl) return validatedCallbackWssUrl;
+
+  const configuredCallbackAssistantId = extractPlatformCallbackAssistantId(raw);
+
+  if (normalized && !configuredCallbackAssistantId) {
+    return toWebSocketBaseUrl(normalized);
   }
-  return undefined;
+
+  return resolveVelayBaseWssUrl(
+    config,
+    configuredCallbackAssistantId ?? platformAssistantId,
+  );
 }
 
 /**

package/src/slack/normalize.ts

@@ -1,4 +1,5 @@
 import { renderSlackTextForModel } from "@vellumai/slack-text";
+import { createHash } from "node:crypto";
 import type { GatewayConfig } from "../config.js";
 import { fetchImpl } from "../fetch.js";
 import { resolveAssistant, isRejection } from "../routing/resolve-assistant.js";
@@ -11,8 +12,20 @@ import type { GatewayInboundEvent } from "../types.js";
 interface SlackUserInfo {
   displayName: string;
   username: string;
+  timezone?: string;
+  timezoneLabel?: string;
+  timezoneOffsetSeconds?: number;
 }
 
+export type SlackUserActorFields = Pick<
+  SlackUserInfo,
+  | "displayName"
+  | "username"
+  | "timezone"
+  | "timezoneLabel"
+  | "timezoneOffsetSeconds"
+>;
+
 interface SlackChannelInfo {
   name: string;
 }
@@ -48,6 +61,16 @@ const inFlightChannelFetches = new Map<
   Promise<SlackChannelInfo | undefined>
 >();
 
+function slackUserCacheKey(userId: string, botToken: string): string {
+  const authScope = createHash("sha256").update(botToken).digest("hex");
+  return `${authScope}:${userId}`;
+}
+
+function slackChannelCacheKey(channelId: string, botToken: string): string {
+  const authScope = createHash("sha256").update(botToken).digest("hex");
+  return `${authScope}:${channelId}`;
+}
+
 function evictExpired<T>(cache: Map<string, CacheEntry<T>>): void {
   const now = Date.now();
   for (const [key, entry] of cache) {
@@ -106,11 +129,12 @@ export async function resolveSlackUser(
   userId: string,
   botToken: string,
 ): Promise<SlackUserInfo | undefined> {
-  const cached = cacheGet(userInfoCache, userId);
+  const cacheKey = slackUserCacheKey(userId, botToken);
+  const cached = cacheGet(userInfoCache, cacheKey);
   if (cached) return cached;
 
   // If another caller is already fetching this user, reuse that promise
-  const existing = inFlightUserFetches.get(userId);
+  const existing = inFlightUserFetches.get(cacheKey);
   if (existing) return existing;
 
   const fetchPromise = (async (): Promise<SlackUserInfo | undefined> => {
@@ -129,6 +153,9 @@ export async function resolveSlackUser(
         user?: {
           name?: string;
           real_name?: string;
+          tz?: string;
+          tz_label?: string;
+          tz_offset?: number;
           profile?: { display_name?: string; real_name?: string };
         };
       };
@@ -141,11 +168,27 @@ export async function resolveSlackUser(
         data.user.name ||
         userId;
       const username = data.user.name || userId;
-
-      const info: SlackUserInfo = { displayName, username };
+      const timezone =
+        typeof data.user.tz === "string" ? data.user.tz : undefined;
+      const timezoneLabel =
+        typeof data.user.tz_label === "string" ? data.user.tz_label : undefined;
+      const timezoneOffsetSeconds =
+        typeof data.user.tz_offset === "number"
+          ? data.user.tz_offset
+          : undefined;
+
+      const info: SlackUserInfo = {
+        displayName,
+        username,
+        ...(timezone !== undefined ? { timezone } : {}),
+        ...(timezoneLabel !== undefined ? { timezoneLabel } : {}),
+        ...(timezoneOffsetSeconds !== undefined
+          ? { timezoneOffsetSeconds }
+          : {}),
+      };
       cacheSet(
         userInfoCache,
-        userId,
+        cacheKey,
         info,
         USER_CACHE_TTL_MS,
         USER_CACHE_MAX_SIZE,
@@ -156,11 +199,11 @@ export async function resolveSlackUser(
     }
   })();
 
-  inFlightUserFetches.set(userId, fetchPromise);
+  inFlightUserFetches.set(cacheKey, fetchPromise);
   try {
     return await fetchPromise;
   } finally {
-    inFlightUserFetches.delete(userId);
+    inFlightUserFetches.delete(cacheKey);
   }
 }
 
@@ -175,10 +218,11 @@ export async function resolveSlackChannel(
   channelId: string,
   botToken: string,
 ): Promise<SlackChannelInfo | undefined> {
-  const cached = cacheGet(channelInfoCache, channelId);
+  const cacheKey = slackChannelCacheKey(channelId, botToken);
+  const cached = cacheGet(channelInfoCache, cacheKey);
   if (cached) return cached;
 
-  const existing = inFlightChannelFetches.get(channelId);
+  const existing = inFlightChannelFetches.get(cacheKey);
   if (existing) return existing;
 
   const fetchPromise = (async (): Promise<SlackChannelInfo | undefined> => {
@@ -207,7 +251,7 @@ export async function resolveSlackChannel(
       const info: SlackChannelInfo = { name };
       cacheSet(
         channelInfoCache,
-        channelId,
+        cacheKey,
         info,
         CHANNEL_CACHE_TTL_MS,
         CHANNEL_CACHE_MAX_SIZE,
@@ -218,11 +262,11 @@ export async function resolveSlackChannel(
     }
   })();
 
-  inFlightChannelFetches.set(channelId, fetchPromise);
+  inFlightChannelFetches.set(cacheKey, fetchPromise);
   try {
     return await fetchPromise;
   } finally {
-    inFlightChannelFetches.delete(channelId);
+    inFlightChannelFetches.delete(cacheKey);
   }
 }
 
@@ -235,8 +279,9 @@ export function resolveSlackUserSync(
   userId: string,
   botToken: string,
 ): SlackUserInfo | undefined {
-  const cached = cacheGet(userInfoCache, userId);
-  if (!cached && !inFlightUserFetches.has(userId)) {
+  const cacheKey = slackUserCacheKey(userId, botToken);
+  const cached = cacheGet(userInfoCache, cacheKey);
+  if (!cached && !inFlightUserFetches.has(cacheKey)) {
     // Fire-and-forget: warm the cache for next time
     resolveSlackUser(userId, botToken).catch(() => {});
   }
@@ -395,6 +440,22 @@ function renderSlackInboundText(
   });
 }
 
+export function slackUserActorFields(
+  userInfo: SlackUserInfo,
+): SlackUserActorFields {
+  return {
+    displayName: userInfo.displayName,
+    username: userInfo.username,
+    ...(userInfo.timezone !== undefined ? { timezone: userInfo.timezone } : {}),
+    ...(userInfo.timezoneLabel !== undefined
+      ? { timezoneLabel: userInfo.timezoneLabel }
+      : {}),
+    ...(userInfo.timezoneOffsetSeconds !== undefined
+      ? { timezoneOffsetSeconds: userInfo.timezoneOffsetSeconds }
+      : {}),
+  };
+}
+
 function extractSlackAttachments(files: SlackFile[] | undefined): Array<{
   type: "image" | "document";
   fileId: string;
@@ -505,10 +566,7 @@ export function normalizeSlackDirectMessage(
       },
       actor: {
         actorExternalId: event.user,
-        ...(userInfo && {
-          displayName: userInfo.displayName,
-          username: userInfo.username,
-        }),
+        ...(userInfo ? slackUserActorFields(userInfo) : {}),
       },
       source: {
         updateId: eventId,
@@ -573,10 +631,7 @@ export function normalizeSlackChannelMessage(
       },
       actor: {
         actorExternalId: event.user,
-        ...(userInfo && {
-          displayName: userInfo.displayName,
-          username: userInfo.username,
-        }),
+        ...(userInfo ? slackUserActorFields(userInfo) : {}),
       },
       source: {
         updateId: eventId,
@@ -638,10 +693,7 @@ export function normalizeSlackAppMention(
       },
       actor: {
         actorExternalId: event.user,
-        ...(userInfo && {
-          displayName: userInfo.displayName,
-          username: userInfo.username,
-        }),
+        ...(userInfo ? slackUserActorFields(userInfo) : {}),
       },
       source: {
         updateId: eventId,

package/src/slack/socket-mode.ts

@@ -25,6 +25,7 @@ import {
   normalizeSlackReactionRemoved,
   resolveSlackChannel,
   resolveSlackUser,
+  slackUserActorFields,
   type SlackAppMentionEvent,
   type SlackDirectMessageEvent,
   type SlackChannelMessageEvent,
@@ -1018,8 +1019,7 @@ export class SlackSocketModeClient {
         ),
       ]);
       if (userInfo) {
-        actor.displayName = userInfo.displayName;
-        actor.username = userInfo.username;
+        Object.assign(actor, slackUserActorFields(userInfo));
       }
     }
 

package/src/twilio/validate-webhook.ts

@@ -182,6 +182,8 @@ export type TwilioValidationSuccess = {
   rawBody: string;
   /** Parsed key-value pairs from the form body. */
   params: Record<string, string>;
+  /** Candidate URL that matched X-Twilio-Signature. */
+  validatedCandidateUrl?: string;
 };
 
 /** Options bag for optional cache injection into Twilio webhook validation. */
@@ -411,5 +413,9 @@ export async function validateTwilioWebhookRequest(
     log.info(successLogContext, "Twilio webhook signature validated");
   }
 
-  return { rawBody, params };
+  return {
+    rawBody,
+    params,
+    validatedCandidateUrl: validatingCandidate.url,
+  };
 }

package/src/types.ts

@@ -6,4 +6,5 @@ export type {
   WhatsAppInboundEvent,
   SlackInboundEvent,
   EmailInboundEvent,
+  A2aInboundEvent,
 } from "./channels/inbound-event.js";

package/src/velay/client.test.ts

@@ -44,6 +44,7 @@ const WS_CLOSED = WebSocket.CLOSED;
 function makeCredentials(values: Record<string, string | undefined>) {
   return {
     get: async (key: string) => values[key],
+    onInvalidate: () => () => {},
   } as unknown as CredentialCache;
 }
 
@@ -526,6 +527,105 @@ describe("VelayTunnelClient", () => {
     expect(reconnectDelays).toEqual([10, 20, 10]);
   });
 
+  test("refreshCredentials cancels stale credential backoff and reconnects immediately", async () => {
+    const sockets: FakeWebSocket[] = [];
+    const reconnectDelays: number[] = [];
+    const reconnectCallbacks: Array<() => void> = [];
+    const credentialValues: Record<string, string | undefined> = {};
+    const credentials = makeCredentials(credentialValues);
+    const client = new VelayTunnelClient({
+      velayBaseUrl: "http://velay.example.test",
+      gatewayLoopbackBaseUrl: "http://127.0.0.1:7830",
+      credentials,
+      configFile: makeConfigFileCache({ count: 0 }),
+      webSocketConstructor: makeFakeWebSocketConstructor(sockets),
+      reconnect: { baseDelayMs: 10, maxDelayMs: 80, jitterRatio: 0 },
+      heartbeat: { intervalMs: 0, readTimeoutMs: 0 },
+      timerApi: makeManualTimerApi(reconnectDelays, reconnectCallbacks),
+    });
+
+    client.start();
+    await flushPromises();
+
+    expect(sockets).toHaveLength(0);
+    expect(reconnectDelays).toEqual([10]);
+
+    credentialValues[credentialKey("vellum", "assistant_api_key")] =
+      "api-key-123";
+    credentialValues[credentialKey("vellum", "platform_assistant_id")] =
+      "asst-123";
+
+    client.refreshCredentials("vellum credentials changed");
+    await flushPromises();
+
+    expect(sockets).toHaveLength(1);
+    expect(sockets[0].options).toEqual({
+      protocols: [VELAY_TUNNEL_SUBPROTOCOL],
+      headers: {
+        Authorization: "Api-Key api-key-123",
+        "X-Vellum-Velay-Allowed-Paths": VELAY_ALLOWED_PATHS_HEADER_VALUE,
+      },
+    });
+    expect(reconnectDelays).toEqual([10]);
+  });
+
+  test("refreshCredentials retries immediately when credentials change during active connect", async () => {
+    const sockets: FakeWebSocket[] = [];
+    const reconnectDelays: number[] = [];
+    const apiKeyCredential = credentialKey("vellum", "assistant_api_key");
+    const assistantIdCredential = credentialKey(
+      "vellum",
+      "platform_assistant_id",
+    );
+    let resolveFirstApiKeyRead: (value: string | undefined) => void = () => {};
+    const firstApiKeyRead = new Promise<string | undefined>((resolve) => {
+      resolveFirstApiKeyRead = resolve;
+    });
+    let useFreshCredentials = false;
+    const credentials = {
+      get: async (key: string) => {
+        if (key === apiKeyCredential) {
+          return useFreshCredentials ? "api-key-123" : firstApiKeyRead;
+        }
+        if (key === assistantIdCredential) return "asst-123";
+        return undefined;
+      },
+      onInvalidate: () => () => {},
+    } as unknown as CredentialCache;
+    const client = new VelayTunnelClient({
+      velayBaseUrl: "http://velay.example.test",
+      gatewayLoopbackBaseUrl: "http://127.0.0.1:7830",
+      credentials,
+      configFile: makeConfigFileCache({ count: 0 }),
+      webSocketConstructor: makeFakeWebSocketConstructor(sockets),
+      reconnect: { baseDelayMs: 10, maxDelayMs: 80, jitterRatio: 0 },
+      heartbeat: { intervalMs: 0, readTimeoutMs: 0 },
+      timerApi: makeTimerApi(reconnectDelays),
+    });
+
+    client.start();
+    await flushPromises();
+
+    expect(sockets).toHaveLength(0);
+    expect(reconnectDelays).toEqual([]);
+
+    client.refreshCredentials("vellum credentials changed");
+    useFreshCredentials = true;
+    resolveFirstApiKeyRead(undefined);
+    await flushPromises();
+
+    expect(sockets).toHaveLength(1);
+    expect(sockets[0].options).toEqual({
+      protocols: [VELAY_TUNNEL_SUBPROTOCOL],
+      headers: {
+        Authorization: "Api-Key api-key-123",
+        "X-Vellum-Velay-Allowed-Paths": VELAY_ALLOWED_PATHS_HEADER_VALUE,
+      },
+    });
+    expect(reconnectDelays).toEqual([]);
+    await client.stop();
+  });
+
   test("writes only ingress.publicBaseUrl when publishing a Velay URL", async () => {
     const sockets: FakeWebSocket[] = [];
     writeConfig({

package/src/velay/client.ts

@@ -92,6 +92,7 @@ export class VelayTunnelClient {
   private readTimeoutTimer: unknown = null;
   private peerHeartbeatConfirmed = false;
   private publishedPublicBaseUrl: string | undefined;
+  private credentialRefreshPending = false;
   private unsubscribeConfigInvalidation: (() => void) | undefined;
 
   constructor(private readonly options: VelayTunnelClientOptions) {
@@ -127,6 +128,37 @@ export class VelayTunnelClient {
     };
   }
 
+  refreshCredentials(reason = "credentials changed"): void {
+    if (!this.running) return;
+
+    this.reconnectAttempt = 0;
+    if (this.reconnectTimer) {
+      this.timerApi.clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    const ws = this.ws;
+    if (ws) {
+      log.info(
+        { reason },
+        "Restarting Velay tunnel with refreshed credentials",
+      );
+      this.disconnectActiveWebSocket(ws, 1000, "credentials changed");
+      return;
+    }
+
+    if (this.connecting) {
+      this.credentialRefreshPending = true;
+      log.info(
+        { reason },
+        "Queued Velay credential refresh behind active connect",
+      );
+      return;
+    }
+
+    this.connectForCredentialRefresh(reason);
+  }
+
   start(): void {
     if (this.running) return;
     this.running = true;
@@ -145,6 +177,7 @@ export class VelayTunnelClient {
   async stop(): Promise<void> {
     this.running = false;
     this.connecting = false;
+    this.credentialRefreshPending = false;
     this.unsubscribeConfigInvalidation?.();
     this.unsubscribeConfigInvalidation = undefined;
     if (this.reconnectTimer) {
@@ -192,6 +225,9 @@ export class VelayTunnelClient {
     } catch (err) {
       this.connecting = false;
       log.warn({ err }, "Failed to read Velay tunnel credentials");
+      if (this.consumePendingCredentialRefresh("credentials read failed")) {
+        return;
+      }
       this.scheduleReconnect();
       return;
     }
@@ -205,6 +241,9 @@ export class VelayTunnelClient {
     const platformAssistantId = platformAssistantIdRaw?.trim() || undefined;
     if (!apiKey) {
       this.connecting = false;
+      if (this.consumePendingCredentialRefresh("assistant API key missing")) {
+        return;
+      }
       log.info("Velay tunnel waiting for assistant API key");
       this.scheduleReconnect();
       return;
@@ -217,6 +256,9 @@ export class VelayTunnelClient {
     } catch (err) {
       this.connecting = false;
       log.error({ err }, "Invalid Velay base URL");
+      if (this.consumePendingCredentialRefresh("Velay base URL invalid")) {
+        return;
+      }
       this.scheduleReconnect();
       return;
     }
@@ -261,14 +303,45 @@ export class VelayTunnelClient {
           this.disconnectActiveWebSocket(ws);
         }
       });
+
+      if (this.credentialRefreshPending) {
+        this.credentialRefreshPending = false;
+        log.info(
+          "Restarting Velay tunnel because credentials changed during connect",
+        );
+        this.disconnectActiveWebSocket(ws, 1000, "credentials changed");
+      }
     } catch (err) {
       this.ws = null;
       this.connecting = false;
       log.warn({ err }, "Failed to connect Velay tunnel");
+      if (this.consumePendingCredentialRefresh("WebSocket connect failed")) {
+        return;
+      }
       this.scheduleReconnect();
     }
   }
 
+  private connectForCredentialRefresh(reason: string): void {
+    this.connect().catch((err) => {
+      this.connecting = false;
+      log.error({ err, reason }, "Velay credential refresh reconnect failed");
+      this.scheduleReconnect();
+    });
+  }
+
+  private consumePendingCredentialRefresh(reason: string): boolean {
+    if (!this.credentialRefreshPending || !this.running) return false;
+
+    this.credentialRefreshPending = false;
+    log.info(
+      { reason },
+      "Retrying Velay tunnel connect with refreshed credentials",
+    );
+    this.connectForCredentialRefresh(reason);
+    return true;
+  }
+
   private async handleMessage(
     data: unknown,
     originWs: WebSocket,