@vellumai/vellum-gateway 0.8.6 → 0.8.7

package/ARCHITECTURE.md

@@ -95,11 +95,11 @@ The gateway exposes a REST API for reading and mutating assistant feature flags.
 | GET    | `/v1/feature-flags`      | List all declared assistant feature flags from the defaults registry, merged with persisted values from the feature flag store. Returns `{ flags: FeatureFlagEntry[] }` where each entry has `key`, `enabled`, `defaultEnabled`, and `description`. |
 | PATCH  | `/v1/feature-flags/:key` | Set a single assistant feature flag. Body: `{ "enabled": true\|false }`. Key must be a simple kebab-case flag key declared in the defaults registry. Writes to `~/.vellum/protected/feature-flags.json`.                                            |
 
-**Unified registry:** All declared feature flags and their default values are defined in the unified registry at `meta/feature-flags/feature-flag-registry.json` (bundled copy at `gateway/src/feature-flag-registry.json`). The gateway loads this registry on startup via `gateway/src/feature-flag-defaults.ts`, filtering to `scope: "assistant"` flags. Labels come from the registry. The GET endpoint merges persisted overrides with remote values and registry defaults to produce the full flag list. Once a remote snapshot exists, declared flags missing from that snapshot fail closed to `false`; this handles flags that are declared locally but unregistered on the platform. The PATCH endpoint validates that the target flag key exists in the registry before accepting a write. Only declared keys are exposed by this API.
+**Unified registry:** All declared feature flags and their default values are defined in the unified registry at `meta/feature-flags/feature-flag-registry.json` (bundled copy at `gateway/src/feature-flag-registry.json`). The gateway loads this registry on startup via `gateway/src/feature-flag-defaults.ts`, filtering to `scope: "assistant"` flags. Labels come from the registry. The GET endpoint merges persisted overrides with explicit remote values and registry defaults to produce the full flag list. Declared flags missing from a remote snapshot fall back to their registry `defaultEnabled`; undeclared keys are rejected by writes and fail closed in direct resolver calls. The PATCH endpoint validates that the target flag key exists in the registry before accepting a write. Only declared keys are exposed by this API.
 
 **Flag key format:** The canonical key format is simple kebab-case (e.g., `browser`, `ces-tools`). Only keys matching this pattern and declared in the registry are accepted by the PATCH endpoint; other patterns are rejected with 400. All writes use the canonical format and are stored in the protected feature flag store (`~/.vellum/protected/feature-flags.json`).
 
-**Storage:** Flag overrides are persisted in `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store uses a versioned JSON format (`{ version: 1, values: Record<string, boolean> }`). Remote platform snapshots are persisted separately in `feature-flags-remote.json`; local overrides win over remote values, remote values win over registry defaults, and missing remote values fail closed when a remote snapshot exists. The gateway writes atomically (temp file + rename, 0o600 permissions). The daemon's config watcher monitors the protected directory and hot-reloads flag changes, so flag mutations take effect on the next session or tool resolution without a restart.
+**Storage:** Flag overrides are persisted in `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store uses a versioned JSON format (`{ version: 1, values: Record<string, boolean> }`). Remote platform snapshots are persisted separately in `feature-flags-remote.json`; local overrides win over remote values, explicit remote values win over registry defaults, and missing remote values fall back to registry defaults. The gateway writes atomically (temp file + rename, 0o600 permissions). The daemon's config watcher monitors the protected directory and hot-reloads flag changes, so flag mutations take effect on the next session or tool resolution without a restart.
 
 **Token separation (authentication boundary):**
 

package/package.json

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

package/src/__tests__/feature-flag-resolver.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { testSecurityDir } from "./test-preload.js";
+
+const protectedDir = testSecurityDir;
+const defaultsPath = join(protectedDir, "feature-flag-registry.json");
+
+const TEST_REGISTRY = {
+  version: 1,
+  flags: [
+    {
+      id: "browser",
+      scope: "assistant",
+      key: "browser",
+      label: "Browser",
+      description: "Browser skill",
+      defaultEnabled: true,
+    },
+    {
+      id: "a2a-channel",
+      scope: "assistant",
+      key: "a2a-channel",
+      label: "A2A Channel",
+      description: "A2A channel integration",
+      defaultEnabled: false,
+    },
+  ],
+};
+
+beforeEach(() => {
+  mkdirSync(protectedDir, { recursive: true });
+  writeFileSync(defaultsPath, JSON.stringify(TEST_REGISTRY, null, 2));
+  _setRegistryCandidateOverrides([defaultsPath]);
+  resetFeatureFlagDefaultsCache();
+  clearFeatureFlagStoreCache();
+  clearRemoteFeatureFlagStoreCache();
+});
+
+afterEach(() => {
+  try {
+    rmSync(protectedDir, { recursive: true, force: true });
+    mkdirSync(protectedDir, { recursive: true });
+  } catch {
+    // best effort cleanup
+  }
+  _setRegistryCandidateOverrides(null);
+  resetFeatureFlagDefaultsCache();
+  clearFeatureFlagStoreCache();
+  clearRemoteFeatureFlagStoreCache();
+});
+
+const { isFeatureFlagEnabled } = await import("../feature-flag-resolver.js");
+const { resetFeatureFlagDefaultsCache, _setRegistryCandidateOverrides } =
+  await import("../feature-flag-defaults.js");
+const { clearFeatureFlagStoreCache, writeFeatureFlag } =
+  await import("../feature-flag-store.js");
+const { clearRemoteFeatureFlagStoreCache, writeRemoteFeatureFlags } =
+  await import("../feature-flag-remote-store.js");
+
+describe("isFeatureFlagEnabled", () => {
+  test("uses registry defaults when no override exists", () => {
+    expect(isFeatureFlagEnabled("browser")).toBe(true);
+    expect(isFeatureFlagEnabled("a2a-channel")).toBe(false);
+  });
+
+  test("uses persisted overrides for declared flags", () => {
+    writeFeatureFlag("browser", false);
+    writeFeatureFlag("a2a-channel", true);
+
+    expect(isFeatureFlagEnabled("browser")).toBe(false);
+    expect(isFeatureFlagEnabled("a2a-channel")).toBe(true);
+  });
+
+  test("uses explicit remote values for declared flags", () => {
+    writeRemoteFeatureFlags({
+      browser: false,
+      "a2a-channel": true,
+    });
+
+    expect(isFeatureFlagEnabled("browser")).toBe(false);
+    expect(isFeatureFlagEnabled("a2a-channel")).toBe(true);
+  });
+
+  test("ignores persisted and remote values for undeclared flags", () => {
+    writeFeatureFlag("unknown", true);
+    writeRemoteFeatureFlags({ unknown: true });
+
+    expect(isFeatureFlagEnabled("unknown")).toBe(false);
+  });
+});

package/src/__tests__/feature-flags-route.test.ts

@@ -32,11 +32,11 @@ const TEST_REGISTRY = {
       defaultEnabled: true,
     },
     {
-      id: "email-channel",
+      id: "a2a-channel",
       scope: "assistant",
-      key: "email-channel",
-      label: "Email Channel",
-      description: "Email channel integration",
+      key: "a2a-channel",
+      label: "A2A Channel",
+      description: "A2A channel integration",
       defaultEnabled: false,
     },
     {
@@ -248,19 +248,19 @@ describe("GET /v1/feature-flags handler", () => {
   });
 
   test("remote values fill in when no local override exists", async () => {
-    // Write a remote store with email-channel enabled (overriding registry default of false)
+    // Write a remote store with a2a-channel enabled (overriding registry default of false)
     writeFileSync(
       remoteFeatureFlagStorePath,
       JSON.stringify({
         version: 1,
         values: {
-          "email-channel": true,
+          "a2a-channel": true,
         },
       }),
     );
     clearRemoteFeatureFlagStoreCache();
 
-    // No local override for email-channel
+    // No local override for a2a-channel
     if (existsSync(featureFlagStorePath)) {
       rmSync(featureFlagStorePath);
     }
@@ -274,12 +274,12 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    const emailFlag = body.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    const a2aFlag = body.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag).toBeDefined();
+    expect(a2aFlag).toBeDefined();
     // Remote value (true) overrides registry default (false)
-    expect(emailFlag.enabled).toBe(true);
+    expect(a2aFlag.enabled).toBe(true);
   });
 
   test("local overrides take precedence over remote values", async () => {
@@ -289,7 +289,7 @@ describe("GET /v1/feature-flags handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          "email-channel": true,
+          "a2a-channel": true,
         },
       }),
     );
@@ -301,7 +301,7 @@ describe("GET /v1/feature-flags handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          "email-channel": false,
+          "a2a-channel": false,
         },
       }),
     );
@@ -315,38 +315,38 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    const emailFlag = body.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    const a2aFlag = body.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag).toBeDefined();
+    expect(a2aFlag).toBeDefined();
     // Local override (false) takes precedence over remote (true)
-    expect(emailFlag.enabled).toBe(false);
+    expect(a2aFlag.enabled).toBe(false);
   });
 
   test("reflects updated flags after remote sync writes new values (stale cache regression)", async () => {
     // Scenario: the remote poller (RemoteFeatureFlagSync) writes
-    // email-channel: false, the gateway caches it, then a subsequent
-    // poll writes email-channel: true. The GET handler should return
+    // a2a-channel: false, the gateway caches it, then a subsequent
+    // poll writes a2a-channel: true. The GET handler should return
     // the updated value because writeRemoteFeatureFlags() updates
     // both disk and the in-memory cache.
 
-    // Step 1: First poll writes email-channel: false (simulated via
+    // Step 1: First poll writes a2a-channel: false (simulated via
     // writeRemoteFeatureFlags, which is what the poller calls internally).
-    writeRemoteFeatureFlags({ "email-channel": false });
+    writeRemoteFeatureFlags({ "a2a-channel": false });
 
     const handler = createFeatureFlagsGetHandler();
     const res1 = await handler(
       new Request("http://gateway.test/v1/feature-flags"),
     );
     const body1 = await res1.json();
-    const emailFlag1 = body1.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    const a2aFlag1 = body1.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag1.enabled).toBe(false);
+    expect(a2aFlag1.enabled).toBe(false);
 
-    // Step 2: Second poll writes email-channel: true — the poller
+    // Step 2: Second poll writes a2a-channel: true — the poller
     // calls writeRemoteFeatureFlags which updates file + cache.
-    writeRemoteFeatureFlags({ "email-channel": true });
+    writeRemoteFeatureFlags({ "a2a-channel": true });
 
     // Step 3: The GET handler should immediately reflect the update
     // without needing a file-watcher round-trip.
@@ -354,10 +354,10 @@ describe("GET /v1/feature-flags handler", () => {
       new Request("http://gateway.test/v1/feature-flags"),
     );
     const body2 = await res2.json();
-    const emailFlag2 = body2.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    const a2aFlag2 = body2.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag2.enabled).toBe(true);
+    expect(a2aFlag2.enabled).toBe(true);
   });
 
   test("registry default used when neither local nor remote is set", async () => {
@@ -381,13 +381,13 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    // email-channel has defaultEnabled: false in registry
-    const emailFlag = body.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    // a2a-channel has defaultEnabled: false in registry
+    const a2aFlag = body.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag).toBeDefined();
-    expect(emailFlag.enabled).toBe(false);
-    expect(emailFlag.defaultEnabled).toBe(false);
+    expect(a2aFlag).toBeDefined();
+    expect(a2aFlag.enabled).toBe(false);
+    expect(a2aFlag.defaultEnabled).toBe(false);
 
     // browser has defaultEnabled: true in registry
     const browserFlag = body.flags.find(
@@ -398,7 +398,7 @@ describe("GET /v1/feature-flags handler", () => {
     expect(browserFlag.defaultEnabled).toBe(true);
   });
 
-  test("declared flags missing from a remote snapshot default to disabled", async () => {
+  test("declared flags missing from a remote snapshot use their registry defaults", async () => {
     // No local override
     if (existsSync(featureFlagStorePath)) {
       rmSync(featureFlagStorePath);
@@ -411,7 +411,7 @@ describe("GET /v1/feature-flags handler", () => {
       remoteFeatureFlagStorePath,
       JSON.stringify({
         version: 1,
-        values: { "email-channel": true },
+        values: { "a2a-channel": true },
       }),
     );
     clearRemoteFeatureFlagStoreCache();
@@ -424,16 +424,16 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    const emailFlag = body.flags.find(
-      (f: { key: string }) => f.key === "email-channel",
+    const a2aFlag = body.flags.find(
+      (f: { key: string }) => f.key === "a2a-channel",
     );
-    expect(emailFlag.enabled).toBe(true);
+    expect(a2aFlag.enabled).toBe(true);
 
     const browserFlag = body.flags.find(
       (f: { key: string }) => f.key === "browser",
     );
     expect(browserFlag).toBeDefined();
-    expect(browserFlag.enabled).toBe(false);
+    expect(browserFlag.enabled).toBe(true);
     expect(browserFlag.defaultEnabled).toBe(true);
   });
 
@@ -498,7 +498,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          "email-channel": true,
+          "a2a-channel": true,
         },
       }),
     );
@@ -517,7 +517,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     // Both old and new values should be persisted
     clearFeatureFlagStoreCache();
     const persisted = readPersistedFeatureFlags();
-    expect(persisted["email-channel"]).toBe(true);
+    expect(persisted["a2a-channel"]).toBe(true);
     expect(persisted["browser"]).toBe(true);
   });
 
@@ -527,12 +527,12 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
 
     const handler = createFeatureFlagsPatchHandler();
     const res = await handler(
-      new Request("http://gateway.test/v1/feature-flags/email-channel", {
+      new Request("http://gateway.test/v1/feature-flags/a2a-channel", {
         method: "PATCH",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ enabled: true }),
       }),
-      "email-channel",
+      "a2a-channel",
     );
 
     expect(res.status).toBe(200);
@@ -540,7 +540,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
 
     clearFeatureFlagStoreCache();
     const persisted = readPersistedFeatureFlags();
-    expect(persisted["email-channel"]).toBe(true);
+    expect(persisted["a2a-channel"]).toBe(true);
   });
 
   // Validation tests
@@ -633,7 +633,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
   test("accepts valid declared kebab-case key formats", async () => {
     const handler = createFeatureFlagsPatchHandler();
 
-    const validKeys = ["browser", "email-channel"];
+    const validKeys = ["browser", "a2a-channel"];
 
     for (const key of validKeys) {
       clearFeatureFlagStoreCache();
@@ -704,7 +704,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       featureFlagStorePath,
       JSON.stringify({
         version: 1,
-        values: { "email-channel": true },
+        values: { "a2a-channel": true },
       }),
     );
     clearFeatureFlagStoreCache();
@@ -723,7 +723,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     const raw = readFileSync(featureFlagStorePath, "utf-8");
     const data = JSON.parse(raw);
     expect(data.version).toBe(1);
-    expect(data.values["email-channel"]).toBe(true);
+    expect(data.values["a2a-channel"]).toBe(true);
     expect(data.values["browser"]).toBe(false);
 
     // Verify no temp files left behind
@@ -737,7 +737,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     const handler = createFeatureFlagsPatchHandler();
 
     // Fire multiple concurrent PATCH requests at the same time
-    const flagKeys = ["browser", "email-channel"];
+    const flagKeys = ["browser", "a2a-channel"];
 
     const results = await Promise.all(
       flagKeys.map((key) =>

package/src/__tests__/ipc-feature-flag-routes.test.ts

@@ -30,11 +30,11 @@ const TEST_REGISTRY = {
       defaultEnabled: true,
     },
     {
-      id: "email-channel",
+      id: "a2a-channel",
       scope: "assistant",
-      key: "email-channel",
-      label: "Email Channel",
-      description: "Email channel integration",
+      key: "a2a-channel",
+      label: "A2A Channel",
+      description: "A2A channel integration",
       defaultEnabled: false,
     },
     {
@@ -167,9 +167,9 @@ describe("IPC feature flag routes", () => {
     expect(res.result).toBeDefined();
 
     const flags = res.result as Record<string, boolean>;
-    // browser defaults to true, email-channel defaults to false
+    // browser defaults to true, a2a-channel defaults to false
     expect(flags["browser"]).toBe(true);
-    expect(flags["email-channel"]).toBe(false);
+    expect(flags["a2a-channel"]).toBe(false);
   });
 
   test("get_feature_flags merges persisted values over defaults", async () => {
@@ -188,7 +188,7 @@ describe("IPC feature flag routes", () => {
     expect(res.error).toBeUndefined();
     const flags = res.result as Record<string, boolean>;
     expect(flags["browser"]).toBe(false); // overridden from default true
-    expect(flags["email-channel"]).toBe(false); // still default
+    expect(flags["a2a-channel"]).toBe(false); // still default
   });
 
   test("get_feature_flags merges remote values when no local override", async () => {
@@ -196,7 +196,7 @@ describe("IPC feature flag routes", () => {
       remoteFeatureFlagStorePath,
       JSON.stringify({
         version: 1,
-        values: { "email-channel": true },
+        values: { "a2a-channel": true },
       }),
     );
     clearRemoteFeatureFlagStoreCache();
@@ -212,15 +212,15 @@ describe("IPC feature flag routes", () => {
 
     expect(res.error).toBeUndefined();
     const flags = res.result as Record<string, boolean>;
-    expect(flags["email-channel"]).toBe(true); // remote overrides default
+    expect(flags["a2a-channel"]).toBe(true); // remote overrides default
   });
 
-  test("get_feature_flags disables declared flags missing from a remote snapshot", async () => {
+  test("get_feature_flags falls back to registry defaults for flags missing from a remote snapshot", async () => {
     writeFileSync(
       remoteFeatureFlagStorePath,
       JSON.stringify({
         version: 1,
-        values: { "email-channel": true },
+        values: { "a2a-channel": true },
       }),
     );
     clearRemoteFeatureFlagStoreCache();
@@ -235,8 +235,8 @@ describe("IPC feature flag routes", () => {
 
     expect(res.error).toBeUndefined();
     const flags = res.result as Record<string, boolean>;
-    expect(flags["email-channel"]).toBe(true);
-    expect(flags["browser"]).toBe(false);
+    expect(flags["a2a-channel"]).toBe(true);
+    expect(flags["browser"]).toBe(true);
   });
 
   test("get_feature_flag returns value for a known flag", async () => {

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

@@ -77,10 +77,39 @@ function activeThreadRows(): Array<{ threadTs: string; channelId: string }> {
   return new SlackStore(getGatewayDb()).listActiveThreadsWithChannel();
 }
 
+function rawActiveThreadRows(): Array<{
+  threadTs: string;
+  channelId: string | null;
+}> {
+  const rawDb = (getGatewayDb() as unknown as { $client: unknown }).$client as {
+    prepare: (sql: string) => {
+      all: () => Array<{ thread_ts: string; channel_id: string | null }>;
+    };
+  };
+  return rawDb
+    .prepare("SELECT thread_ts, channel_id FROM slack_active_threads")
+    .all()
+    .map((row) => ({
+      threadTs: row.thread_ts,
+      channelId: row.channel_id,
+    }));
+}
+
 function trackThread(): void {
   new SlackStore(getGatewayDb()).trackThread(THREAD_TS, CHANNEL_ID, 60_000);
 }
 
+function trackLegacyThreadWithoutChannel(): void {
+  const rawDb = (getGatewayDb() as unknown as { $client: unknown }).$client as {
+    prepare: (sql: string) => { run: (...params: unknown[]) => void };
+  };
+  rawDb
+    .prepare(
+      "INSERT INTO slack_active_threads (thread_ts, channel_id, tracked_at, expires_at) VALUES (?, NULL, ?, ?)",
+    )
+    .run(THREAD_TS, Date.now(), Date.now() + 60_000);
+}
+
 describe("IPC Slack thread routes", () => {
   let server: InstanceType<typeof GatewayIpcServer>;
   let client: Socket;
@@ -135,6 +164,24 @@ describe("IPC Slack thread routes", () => {
     ]);
   });
 
+  test("detach_slack_active_thread removes a legacy active thread without channel", async () => {
+    trackLegacyThreadWithoutChannel();
+
+    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(rawActiveThreadRows()).toEqual([]);
+  });
+
   test("detach_slack_active_thread does not remove channel mismatches", async () => {
     trackThread();