@vellumai/vellum-gateway 0.8.2 → 0.8.4

package/ARCHITECTURE.md

@@ -298,7 +298,7 @@ The assistant runtime reads this URL via the centralized `public-ingress-urls.ts
 
 Velay is a platform-managed tunnel for assistant-hosted HTTP and WebSocket traffic. When it is active, Velay publishes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`.
 
-When `VELAY_BASE_URL` is present in the gateway environment, the gateway creates `VelayTunnelClient` but starts it only after Twilio setup has been started in the workspace. On boot, existing Twilio credentials or existing `twilio.accountSid` / `twilio.phoneNumber` config count as prior setup, and successful credential setup persists `twilio.setupStarted: true` for future boots. Before credential-backed startup side effects run, the gateway clears any stale Velay-managed `ingress.publicBaseUrl`; if setup has not started, it does this without opening a tunnel. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. The gateway writes that URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
+When `VELAY_BASE_URL` is present in the gateway environment, the gateway creates `VelayTunnelClient` but starts it only after Twilio setup has been started in the workspace. The Twilio setup skill writes `twilio.setupStarted: true` at the beginning of setup so the tunnel can open while credentials and phone-number selection are still in progress. On boot, existing Twilio credentials or existing `twilio.accountSid` / `twilio.phoneNumber` config also count as prior setup. Before credential-backed startup side effects run, the gateway clears any stale Velay-managed `ingress.publicBaseUrl`; if setup has not started, it does this without opening a tunnel. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. If Vellum platform credentials change while the tunnel is already running or waiting on backoff, the gateway asks the client to reconnect with fresh credentials instead of waiting for process restart. The gateway writes the registered URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
 
 Velay forwards both HTTP request frames and WebSocket frames into the local gateway loopback listener:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/config-file-watcher.test.ts

@@ -42,6 +42,31 @@ function makeEvent(
   };
 }
 
+function makeManualIntervalTimer() {
+  let intervalFn: (() => void) | undefined;
+  let cleared = false;
+  type IntervalHandle = ReturnType<typeof setInterval>;
+  const timer = 1 as unknown as IntervalHandle;
+  return {
+    timerApi: {
+      setInterval: (fn: () => void, _delayMs: number) => {
+        intervalFn = fn;
+        return timer;
+      },
+      clearInterval: (_timer: IntervalHandle) => {
+        cleared = true;
+      },
+    },
+    runInterval: () => {
+      if (!intervalFn) {
+        throw new Error("interval was not scheduled");
+      }
+      intervalFn();
+    },
+    isCleared: () => cleared,
+  };
+}
+
 afterEach(() => {
   try {
     if (existsSync(configPath)) unlinkSync(configPath);
@@ -51,6 +76,38 @@ afterEach(() => {
 });
 
 describe("ConfigFileWatcher", () => {
+  test("polls config changes when file watcher events are missed", () => {
+    const events: ConfigChangeEvent[] = [];
+    const timer = makeManualIntervalTimer();
+    const watcher = new ConfigFileWatcher(
+      (event) => {
+        events.push(event);
+      },
+      { pollIntervalMs: 10, timerApi: timer.timerApi },
+    );
+
+    try {
+      watcher.start();
+      writeConfig({
+        twilio: {
+          setupStarted: true,
+        },
+      });
+
+      timer.runInterval();
+
+      expect(events).toHaveLength(1);
+      expect(events[0].changedKeys).toEqual(new Set(["twilio"]));
+      expect(events[0].changedFields.get("twilio")).toEqual(
+        new Set(["setupStarted"]),
+      );
+    } finally {
+      watcher.stop();
+    }
+
+    expect(timer.isCleared()).toBe(true);
+  });
+
   test("reports shallow ingress fields changed by Velay-managed URL writes", () => {
     writeConfig({
       ingress: {

package/src/__tests__/ipc-slack-thread-routes.test.ts

@@ -0,0 +1,157 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createConnection, type Socket } from "node:net";
+
+import {
+  getGatewayDb,
+  initGatewayDb,
+  resetGatewayDb,
+} from "../db/connection.js";
+import { SlackStore } from "../db/slack-store.js";
+import { slackActiveThreads } from "../db/schema.js";
+import { GatewayIpcServer } from "../ipc/server.js";
+import { slackThreadRoutes } from "../ipc/slack-thread-handlers.js";
+
+const CHANNEL_ID = "CFAKE00001";
+const OTHER_CHANNEL_ID = "COTHER0001";
+const THREAD_TS = "1700000000.000000";
+const OTHER_THREAD_TS = "1700000001.000000";
+
+beforeAll(async () => {
+  await initGatewayDb();
+});
+
+beforeEach(() => {
+  getGatewayDb().delete(slackActiveThreads).run();
+});
+
+afterAll(() => {
+  resetGatewayDb();
+});
+
+function connectClient(path: string): Promise<Socket> {
+  return new Promise((resolve, reject) => {
+    const client = createConnection(path, () => resolve(client));
+    client.on("error", reject);
+  });
+}
+
+function sendRequest(
+  client: Socket,
+  method: string,
+  params?: Record<string, unknown>,
+): Promise<{ id: string; result?: unknown; error?: string }> {
+  return new Promise((resolve, reject) => {
+    const id = randomBytes(4).toString("hex");
+    let buffer = "";
+
+    const onData = (chunk: Buffer) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf("\n");
+      if (newlineIdx !== -1) {
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+        client.off("data", onData);
+        try {
+          resolve(JSON.parse(line));
+        } catch (err) {
+          reject(err);
+        }
+      }
+    };
+
+    client.on("data", onData);
+    client.write(JSON.stringify({ id, method, params }) + "\n");
+  });
+}
+
+function activeThreadRows(): Array<{ threadTs: string; channelId: string }> {
+  return new SlackStore(getGatewayDb()).listActiveThreadsWithChannel();
+}
+
+function trackThread(): void {
+  new SlackStore(getGatewayDb()).trackThread(THREAD_TS, CHANNEL_ID, 60_000);
+}
+
+describe("IPC Slack thread routes", () => {
+  let server: InstanceType<typeof GatewayIpcServer>;
+  let client: Socket;
+
+  afterEach(() => {
+    client?.destroy();
+    server?.stop();
+  });
+
+  async function startServerAndConnect(): Promise<void> {
+    server = new GatewayIpcServer([...slackThreadRoutes]);
+    server.start();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    client = await connectClient(server.getSocketPath());
+  }
+
+  test("detach_slack_active_thread removes a matching active thread", async () => {
+    trackThread();
+
+    await startServerAndConnect();
+    const res = await sendRequest(client, "detach_slack_active_thread", {
+      channelId: CHANNEL_ID,
+      threadTs: THREAD_TS,
+    });
+
+    expect(res.error).toBeUndefined();
+    expect(res.result).toEqual({
+      detached: true,
+      channelId: CHANNEL_ID,
+      threadTs: THREAD_TS,
+    });
+    expect(activeThreadRows()).toEqual([]);
+  });
+
+  test("detach_slack_active_thread is idempotent for an unknown thread", async () => {
+    trackThread();
+
+    await startServerAndConnect();
+    const res = await sendRequest(client, "detach_slack_active_thread", {
+      channelId: CHANNEL_ID,
+      threadTs: OTHER_THREAD_TS,
+    });
+
+    expect(res.error).toBeUndefined();
+    expect(res.result).toEqual({
+      detached: false,
+      channelId: CHANNEL_ID,
+      threadTs: OTHER_THREAD_TS,
+    });
+    expect(activeThreadRows()).toEqual([
+      { threadTs: THREAD_TS, channelId: CHANNEL_ID },
+    ]);
+  });
+
+  test("detach_slack_active_thread does not remove channel mismatches", async () => {
+    trackThread();
+
+    await startServerAndConnect();
+    const res = await sendRequest(client, "detach_slack_active_thread", {
+      channelId: OTHER_CHANNEL_ID,
+      threadTs: THREAD_TS,
+    });
+
+    expect(res.error).toBeUndefined();
+    expect(res.result).toEqual({
+      detached: false,
+      channelId: OTHER_CHANNEL_ID,
+      threadTs: THREAD_TS,
+    });
+    expect(activeThreadRows()).toEqual([
+      { threadTs: THREAD_TS, channelId: CHANNEL_ID },
+    ]);
+  });
+});

package/src/__tests__/route-schema-guard.test.ts

@@ -8,6 +8,7 @@ import {
   TWILIO_STATUS_WEBHOOK_PATH,
   TWILIO_VOICE_WEBHOOK_PATH,
 } from "@vellumai/service-contracts/twilio-ingress";
+import { A2A_AGENT_CARD_PATH } from "../http/routes/a2a-routes.js";
 import { buildSchema } from "../schema.js";
 
 /** A route extracted from source: path + optional HTTP method. */
@@ -17,6 +18,7 @@ interface ExtractedRoute {
 }
 
 const ROUTE_PATH_CONSTANTS: Record<string, string> = {
+  A2A_AGENT_CARD_PATH,
   TWILIO_CONNECT_ACTION_WEBHOOK_PATH,
   TWILIO_MEDIA_STREAM_WEBHOOK_PATH,
   TWILIO_RELAY_WEBHOOK_PATH,
@@ -169,6 +171,8 @@ const EXCLUDED_FROM_SCHEMA = new Set([
   "catch-all",
   // Loopback-only pairing endpoint — not part of the public gateway API
   "/v1/pair",
+  // A2A agent card discovery — read-only, unauthenticated per spec
+  "/.well-known/agent-card.json",
 ]);
 
 // ── Schema paths that don't map to a discrete route definition ──

package/src/__tests__/slack-display-name.test.ts

@@ -1,5 +1,9 @@
 import { describe, test, expect, mock, beforeEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
+import type {
+  RuntimeInboundPayload,
+  RuntimeInboundResponse,
+} from "../runtime/client.js";
 
 type FetchFn = (
   input: string | URL | Request,
@@ -8,20 +12,46 @@ type FetchFn = (
 let fetchMock: ReturnType<typeof mock<FetchFn>> = mock(
   async () => new Response(),
 );
+let runtimePayloads: RuntimeInboundPayload[] = [];
+const forwardToRuntimeMock = mock(
+  async (
+    _config: GatewayConfig,
+    payload: RuntimeInboundPayload,
+  ): Promise<RuntimeInboundResponse> => {
+    runtimePayloads.push(payload);
+    return { accepted: true, duplicate: false, eventId: "runtime-event-1" };
+  },
+);
 
 mock.module("../fetch.js", () => ({
   fetchImpl: (...args: Parameters<FetchFn>) => fetchMock(...args),
 }));
 
+mock.module("../runtime/client.js", () => ({
+  CircuitBreakerOpenError: class CircuitBreakerOpenError extends Error {
+    readonly retryAfterSecs: number;
+
+    constructor(retryAfterSecs: number) {
+      super("Circuit breaker is open");
+      this.retryAfterSecs = retryAfterSecs;
+    }
+  },
+  forwardToRuntime: (...args: Parameters<typeof forwardToRuntimeMock>) =>
+    forwardToRuntimeMock(...args),
+}));
+
 const {
   normalizeSlackAppMention,
   resolveSlackChannel,
   resolveSlackUser,
+  resolveSlackUserSync,
   clearChannelInfoCache,
+  clearInFlightFetches,
   clearUserInfoCache,
   getChannelInfoCacheSize,
   getUserInfoCacheSize,
 } = await import("../slack/normalize.js");
+const { handleInbound } = await import("../handlers/handle-inbound.js");
 import type { SlackAppMentionEvent } from "../slack/normalize.js";
 
 function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
@@ -67,6 +97,9 @@ function makeEvent(
 beforeEach(() => {
   clearUserInfoCache();
   clearChannelInfoCache();
+  clearInFlightFetches();
+  runtimePayloads = [];
+  forwardToRuntimeMock.mockClear();
 });
 
 describe("resolveSlackUser", () => {
@@ -78,6 +111,9 @@ describe("resolveSlackUser", () => {
           user: {
             name: "jdoe",
             real_name: "Jane Doe",
+            tz: "America/New_York",
+            tz_label: "Eastern Daylight Time",
+            tz_offset: -14400,
             profile: { display_name: "Jane D", real_name: "Jane Doe" },
           },
         }),
@@ -89,6 +125,9 @@ describe("resolveSlackUser", () => {
     expect(info).not.toBeUndefined();
     expect(info!.displayName).toBe("Jane D");
     expect(info!.username).toBe("jdoe");
+    expect(info!.timezone).toBe("America/New_York");
+    expect(info!.timezoneLabel).toBe("Eastern Daylight Time");
+    expect(info!.timezoneOffsetSeconds).toBe(-14400);
   });
 
   test("falls back to real_name when display_name is empty", async () => {
@@ -151,6 +190,100 @@ describe("resolveSlackUser", () => {
     expect(callCount).toBe(1);
     expect(getUserInfoCacheSize()).toBe(1);
   });
+
+  test("scopes cached user info by bot token", async () => {
+    let callCount = 0;
+    fetchMock = mock(async (_input, init) => {
+      callCount++;
+      const auth = new Headers(init?.headers).get("authorization");
+      const user =
+        auth === "Bearer xoxb-team-a"
+          ? {
+              name: "alice",
+              tz: "America/New_York",
+              tz_label: "Eastern Daylight Time",
+              tz_offset: -14400,
+              profile: { display_name: "Alice" },
+            }
+          : {
+              name: "bob",
+              tz: "America/Los_Angeles",
+              tz_label: "Pacific Daylight Time",
+              tz_offset: -25200,
+              profile: { display_name: "Bob" },
+            };
+      return new Response(JSON.stringify({ ok: true, user }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+
+    const [teamAInfo, teamBInfo] = await Promise.all([
+      resolveSlackUser("U_SHARED", "xoxb-team-a"),
+      resolveSlackUser("U_SHARED", "xoxb-team-b"),
+    ]);
+
+    expect(teamAInfo!.displayName).toBe("Alice");
+    expect(teamAInfo!.timezone).toBe("America/New_York");
+    expect(teamBInfo!.displayName).toBe("Bob");
+    expect(teamBInfo!.timezone).toBe("America/Los_Angeles");
+    expect(callCount).toBe(2);
+    expect(getUserInfoCacheSize()).toBe(2);
+
+    await resolveSlackUser("U_SHARED", "xoxb-team-a");
+    await resolveSlackUser("U_SHARED", "xoxb-team-b");
+    expect(callCount).toBe(2);
+  });
+
+  test("sync cache lookup uses the bot token scope", async () => {
+    let callCount = 0;
+    fetchMock = mock(async (_input, init) => {
+      callCount++;
+      const auth = new Headers(init?.headers).get("authorization");
+      const user =
+        auth === "Bearer xoxb-team-a"
+          ? {
+              name: "alice",
+              tz: "America/Denver",
+              tz_label: "Mountain Daylight Time",
+              tz_offset: -21600,
+              profile: { display_name: "Alice" },
+            }
+          : {
+              name: "bob",
+              tz: "Europe/London",
+              tz_label: "British Summer Time",
+              tz_offset: 3600,
+              profile: { display_name: "Bob" },
+            };
+      return new Response(JSON.stringify({ ok: true, user }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+
+    await resolveSlackUser("U_SHARED_SYNC", "xoxb-team-a");
+
+    const teamACached = resolveSlackUserSync("U_SHARED_SYNC", "xoxb-team-a");
+    expect(teamACached!.displayName).toBe("Alice");
+    expect(teamACached!.timezone).toBe("America/Denver");
+
+    const teamBMiss = resolveSlackUserSync("U_SHARED_SYNC", "xoxb-team-b");
+    expect(teamBMiss).toBeUndefined();
+
+    const teamBResolved = await resolveSlackUser(
+      "U_SHARED_SYNC",
+      "xoxb-team-b",
+    );
+    expect(teamBResolved!.displayName).toBe("Bob");
+    expect(teamBResolved!.timezone).toBe("Europe/London");
+
+    const teamBCached = resolveSlackUserSync("U_SHARED_SYNC", "xoxb-team-b");
+    expect(teamBCached!.displayName).toBe("Bob");
+    expect(teamBCached!.timezone).toBe("Europe/London");
+    expect(callCount).toBe(2);
+    expect(getUserInfoCacheSize()).toBe(2);
+  });
 });
 
 describe("resolveSlackChannel", () => {
@@ -217,6 +350,36 @@ describe("resolveSlackChannel", () => {
     expect(callCount).toBe(1);
     expect(getChannelInfoCacheSize()).toBe(1);
   });
+
+  test("scopes cached channel names by bot token", async () => {
+    let callCount = 0;
+    fetchMock = mock(async (_input, init) => {
+      callCount++;
+      const auth = new Headers(init?.headers).get("authorization");
+      const channel =
+        auth === "Bearer xoxb-team-a"
+          ? { id: "C_SHARED", name: "team-a-channel" }
+          : { id: "C_SHARED", name: "team-b-channel" };
+      return new Response(JSON.stringify({ ok: true, channel }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    });
+
+    const [teamAInfo, teamBInfo] = await Promise.all([
+      resolveSlackChannel("C_SHARED", "xoxb-team-a"),
+      resolveSlackChannel("C_SHARED", "xoxb-team-b"),
+    ]);
+
+    expect(teamAInfo!.name).toBe("team-a-channel");
+    expect(teamBInfo!.name).toBe("team-b-channel");
+    expect(callCount).toBe(2);
+    expect(getChannelInfoCacheSize()).toBe(2);
+
+    await resolveSlackChannel("C_SHARED", "xoxb-team-a");
+    await resolveSlackChannel("C_SHARED", "xoxb-team-b");
+    expect(callCount).toBe(2);
+  });
 });
 
 describe("normalizeSlackAppMention with display name", () => {
@@ -273,6 +436,9 @@ describe("normalizeSlackAppMention with display name", () => {
           user: {
             name: "testuser",
             real_name: "Test User",
+            tz: "America/Denver",
+            tz_label: "Mountain Daylight Time",
+            tz_offset: -21600,
             profile: { display_name: "Test U" },
           },
         }),
@@ -296,6 +462,58 @@ describe("normalizeSlackAppMention with display name", () => {
     expect(result).not.toBeNull();
     expect(result!.event.actor.displayName).toBe("Test U");
     expect(result!.event.actor.username).toBe("testuser");
+    expect(result!.event.actor.timezone).toBe("America/Denver");
+    expect(result!.event.actor.timezoneLabel).toBe("Mountain Daylight Time");
+    expect(result!.event.actor.timezoneOffsetSeconds).toBe(-21600);
+  });
+
+  test("forwards cached Slack timezone fields in runtime source metadata", async () => {
+    fetchMock = mock(async () => {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          user: {
+            name: "testuser",
+            real_name: "Test User",
+            tz: "America/Los_Angeles",
+            tz_label: "Pacific Daylight Time",
+            tz_offset: -25200,
+            profile: { display_name: "Test U" },
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    });
+
+    const config = makeConfig();
+    const event = makeEvent({ user: "U_WITH_TZ" });
+    await resolveSlackUser("U_WITH_TZ", "xoxb-test");
+
+    const result = normalizeSlackAppMention(
+      event,
+      "evt-tz-forward",
+      config,
+      undefined,
+      "xoxb-test",
+    );
+    expect(result).not.toBeNull();
+
+    await handleInbound(config, result!.event, {
+      routingOverride: result!.routing,
+    });
+
+    expect(forwardToRuntimeMock).toHaveBeenCalledTimes(1);
+    const forwardedPayload = runtimePayloads[0];
+    expect(forwardedPayload).toBeDefined();
+    expect(forwardedPayload!.sourceMetadata!.timezone).toBe(
+      "America/Los_Angeles",
+    );
+    expect(forwardedPayload!.sourceMetadata!.timezoneLabel).toBe(
+      "Pacific Daylight Time",
+    );
+    expect(forwardedPayload!.sourceMetadata!.timezoneOffsetSeconds).toBe(
+      -25200,
+    );
   });
 
   test("renders cache-warmed mention labels in model-facing content", async () => {