@vellumai/vellum-gateway 0.8.3 → 0.8.5

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 registry defaults to produce the full flag list. 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 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.
 
 **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> }`). The GET endpoint reads from the feature flag store and merges with registry defaults. The gateway writes atomically (temp file + rename, 0o600 permissions). The daemon's config watcher monitors the protected directory and hot-reloads 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, 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.
 
 **Token separation (authentication boundary):**
 

package/package.json

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

package/src/__tests__/auto-approve-conversation-thresholds.test.ts

@@ -60,15 +60,21 @@ function makeDelete(conversationId: string): [Request, string[]] {
 // ---------------------------------------------------------------------------
 
 describe("GET /v1/permissions/thresholds/conversations/:conversationId", () => {
-  test("returns 404 for nonexistent conversation", async () => {
+  test("returns 200 with threshold:null when no override exists", async () => {
+    // "No override" is the common case — every conversation reads this
+    // endpoint to decide whether to apply a per-conversation threshold,
+    // and only a small fraction have one configured. Returning 200 with
+    // `{ threshold: null }` (rather than 404) avoids surfacing a
+    // misleading network error in the browser console for the default
+    // case and matches the IPC contract, which also returns null.
     const handler = createConversationThresholdGetHandler();
     const [req, params] = makeGet("conv-xyz");
 
     const res = await handler(req, params);
-    expect(res.status).toBe(404);
+    expect(res.status).toBe(200);
 
     const body = await res.json();
-    expect(body.error).toBe("No override for this conversation");
+    expect(body).toEqual({ threshold: null });
   });
 
   test("returns threshold after PUT creates it", async () => {
@@ -160,7 +166,7 @@ describe("PUT /v1/permissions/thresholds/conversations/:conversationId", () => {
 });
 
 describe("DELETE /v1/permissions/thresholds/conversations/:conversationId", () => {
-  test("removes existing override, subsequent GET returns 404", async () => {
+  test("removes existing override, subsequent GET returns threshold:null", async () => {
     const putHandler = createConversationThresholdPutHandler();
     const getHandler = createConversationThresholdGetHandler();
     const deleteHandler = createConversationThresholdDeleteHandler();
@@ -174,10 +180,12 @@ describe("DELETE /v1/permissions/thresholds/conversations/:conversationId", () =
     const delRes = await deleteHandler(delReq, delParams);
     expect(delRes.status).toBe(204);
 
-    // Verify gone
+    // Verify gone — GET now reports the absence as a normal 200 result.
     const [getReq, getParams] = makeGet("conv-del");
     const getRes = await getHandler(getReq, getParams);
-    expect(getRes.status).toBe(404);
+    expect(getRes.status).toBe(200);
+    const body = await getRes.json();
+    expect(body).toEqual({ threshold: null });
   });
 
   test("returns 204 on nonexistent conversation (idempotent)", async () => {

package/src/__tests__/config.test.ts

@@ -1,4 +1,9 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { describe, test, expect } from "bun:test";
+
+import { testWorkspaceDir } from "./test-preload.js";
 import { loadConfig } from "../config.js";
 
 describe("config: hardcoded defaults", () => {
@@ -61,6 +66,50 @@ describe("config: hardcoded defaults", () => {
     }
   });
 
+  test("runtimeTimeoutMs is configurable via env var", () => {
+    const saved = process.env.RUNTIME_TIMEOUT_MS;
+    process.env.RUNTIME_TIMEOUT_MS = "300000";
+    try {
+      const config = loadConfig();
+      expect(config.runtimeTimeoutMs).toBe(300000);
+    } finally {
+      if (saved !== undefined) process.env.RUNTIME_TIMEOUT_MS = saved;
+      else delete process.env.RUNTIME_TIMEOUT_MS;
+    }
+  });
+
+  test("runtimeTimeoutMs rejects invalid env var", () => {
+    const saved = process.env.RUNTIME_TIMEOUT_MS;
+    process.env.RUNTIME_TIMEOUT_MS = "0";
+    try {
+      expect(() => loadConfig()).toThrow(
+        "RUNTIME_TIMEOUT_MS must be a positive integer",
+      );
+    } finally {
+      if (saved !== undefined) process.env.RUNTIME_TIMEOUT_MS = saved;
+      else delete process.env.RUNTIME_TIMEOUT_MS;
+    }
+  });
+
+  test("runtimeTimeoutMs rejects non-numeric workspace config values", () => {
+    const saved = process.env.RUNTIME_TIMEOUT_MS;
+    delete process.env.RUNTIME_TIMEOUT_MS;
+    writeFileSync(
+      join(testWorkspaceDir, "config.json"),
+      JSON.stringify({ gateway: { runtimeTimeoutMs: true } }),
+    );
+
+    try {
+      expect(() => loadConfig()).toThrow(
+        "gateway.runtimeTimeoutMs must be a positive integer",
+      );
+    } finally {
+      if (saved !== undefined) process.env.RUNTIME_TIMEOUT_MS = saved;
+      else delete process.env.RUNTIME_TIMEOUT_MS;
+      writeFileSync(join(testWorkspaceDir, "config.json"), "{}");
+    }
+  });
+
   test("gatewayInternalBaseUrl derives from port", () => {
     const saved = process.env.GATEWAY_PORT;
     process.env.GATEWAY_PORT = "8080";

package/src/__tests__/feature-flag-watcher-callback.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Each test gets a fresh, uniquely-named flag directory. Reusing one path
+// across tests (rm + recreate) leaves fs.watch bound to a stale inode, so
+// file events on the recreated directory are silently dropped.
+let flagDir = "";
+
+mock.module("../feature-flag-store.js", () => ({
+  clearFeatureFlagStoreCache: mock(() => {}),
+  getFeatureFlagStorePath: () => join(flagDir, "feature-flags.json"),
+}));
+
+mock.module("../feature-flag-remote-store.js", () => ({
+  refreshRemoteFeatureFlagStoreCache: mock(() => {}),
+  getRemoteFeatureFlagStorePath: () =>
+    join(flagDir, "remote-feature-flags.json"),
+}));
+
+const { FeatureFlagWatcher } = await import("../feature-flag-watcher.js");
+
+describe("FeatureFlagWatcher onChanged callback", () => {
+  beforeEach(() => {
+    flagDir = mkdtempSync(join(tmpdir(), "ff-watcher-test-"));
+    mkdirSync(flagDir, { recursive: true });
+    writeFileSync(join(flagDir, "feature-flags.json"), "{}");
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(flagDir, { recursive: true, force: true });
+    } catch {
+      // best effort
+    }
+  });
+
+  test("calls onChanged after debounce fires on local flag file change", async () => {
+    const onChanged = mock(() => {});
+    const watcher = new FeatureFlagWatcher({ onChanged });
+    watcher.start();
+
+    writeFileSync(
+      join(flagDir, "feature-flags.json"),
+      JSON.stringify({ test: true }),
+    );
+
+    await new Promise((r) => setTimeout(r, 700));
+
+    expect(onChanged).toHaveBeenCalledTimes(1);
+    watcher.stop();
+  });
+
+  test("calls onChanged after debounce fires on remote flag file change", async () => {
+    const onChanged = mock(() => {});
+    const watcher = new FeatureFlagWatcher({ onChanged });
+    watcher.start();
+
+    writeFileSync(
+      join(flagDir, "remote-feature-flags.json"),
+      JSON.stringify({ remote: true }),
+    );
+
+    await new Promise((r) => setTimeout(r, 700));
+
+    expect(onChanged).toHaveBeenCalledTimes(1);
+    watcher.stop();
+  });
+
+  test("does not call onChanged when no callback is provided", async () => {
+    const watcher = new FeatureFlagWatcher();
+    watcher.start();
+
+    writeFileSync(
+      join(flagDir, "feature-flags.json"),
+      JSON.stringify({ test: true }),
+    );
+
+    await new Promise((r) => setTimeout(r, 700));
+
+    // No assertion needed — just verify no error is thrown
+    watcher.stop();
+  });
+});

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

@@ -324,7 +324,7 @@ describe("GET /v1/feature-flags handler", () => {
   });
 
   test("reflects updated flags after remote sync writes new values (stale cache regression)", async () => {
-    // Scenario: the LD poller (RemoteFeatureFlagSync) writes
+    // 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
     // the updated value because writeRemoteFeatureFlags() updates
@@ -398,6 +398,45 @@ describe("GET /v1/feature-flags handler", () => {
     expect(browserFlag.defaultEnabled).toBe(true);
   });
 
+  test("declared flags missing from a remote snapshot default to disabled", async () => {
+    // No local override
+    if (existsSync(featureFlagStorePath)) {
+      rmSync(featureFlagStorePath);
+    }
+    clearFeatureFlagStoreCache();
+
+    // Remote snapshot exists, but browser is absent as it would be when the
+    // platform has no LaunchDarkly value for that key.
+    writeFileSync(
+      remoteFeatureFlagStorePath,
+      JSON.stringify({
+        version: 1,
+        values: { "email-channel": true },
+      }),
+    );
+    clearRemoteFeatureFlagStoreCache();
+
+    const handler = createFeatureFlagsGetHandler();
+    const res = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+
+    const emailFlag = body.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag.enabled).toBe(true);
+
+    const browserFlag = body.flags.find(
+      (f: { key: string }) => f.key === "browser",
+    );
+    expect(browserFlag).toBeDefined();
+    expect(browserFlag.enabled).toBe(false);
+    expect(browserFlag.defaultEnabled).toBe(true);
+  });
+
   test("returns flags when invoked via assistants path without trailing slash", async () => {
     // The macOS client sends GET /v1/assistants/<id>/feature-flags (no trailing slash).
     // The gateway route regex must accept this path.

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

@@ -215,6 +215,30 @@ describe("IPC feature flag routes", () => {
     expect(flags["email-channel"]).toBe(true); // remote overrides default
   });
 
+  test("get_feature_flags disables declared flags missing from a remote snapshot", async () => {
+    writeFileSync(
+      remoteFeatureFlagStorePath,
+      JSON.stringify({
+        version: 1,
+        values: { "email-channel": true },
+      }),
+    );
+    clearRemoteFeatureFlagStoreCache();
+
+    if (existsSync(featureFlagStorePath)) {
+      rmSync(featureFlagStorePath);
+    }
+    clearFeatureFlagStoreCache();
+
+    await startServerAndConnect();
+    const res = await sendRequest(client, "get_feature_flags");
+
+    expect(res.error).toBeUndefined();
+    const flags = res.result as Record<string, boolean>;
+    expect(flags["email-channel"]).toBe(true);
+    expect(flags["browser"]).toBe(false);
+  });
+
   test("get_feature_flag returns value for a known flag", async () => {
     await startServerAndConnect();
     const res = await sendRequest(client, "get_feature_flag", {

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__/remote-feature-flag-sync.test.ts

@@ -38,7 +38,7 @@ const { resetFeatureFlagDefaultsCache, _setRegistryCandidateOverrides } =
 
 // ---------------------------------------------------------------------------
 // Test-local registry with a GA flag (defaultEnabled: true) for the
-// "ignores remote false for GA flags" test. Written to an isolated temp path
+// "normalizes remote false for GA flags" test. Written to an isolated temp path
 // so we never touch the committed registry file.
 // ---------------------------------------------------------------------------
 const testRegistryPath = join(protectedDir, "feature-flag-registry.json");
@@ -459,7 +459,7 @@ describe("RemoteFeatureFlagSync", () => {
     );
   });
 
-  test("ignores remote false for GA flags (defaultEnabled: true in registry)", async () => {
+  test("normalizes remote false for GA flags (defaultEnabled: true in registry)", async () => {
     // The platform sends false for all flags it knows about (blanket-deny).
     // GA flags (defaultEnabled: true in the registry) should not be disabled
     // by remote overrides — only local persisted overrides can do that.
@@ -468,7 +468,8 @@ describe("RemoteFeatureFlagSync", () => {
     fetchMock = mock(async () =>
       Response.json({
         flags: {
-          // GA flag (defaultEnabled: true) — remote false should be dropped
+          // GA flag (defaultEnabled: true) — remote false should be normalized
+          // to true so the missing-key fallback does not disable it.
           "test-ga-flag": false,
           // Gated flag (defaultEnabled: false) — remote false is kept
           "email-channel": false,
@@ -488,8 +489,8 @@ describe("RemoteFeatureFlagSync", () => {
 
     clearRemoteFeatureFlagStoreCache();
     const cached = readRemoteFeatureFlags();
-    // test-ga-flag (GA, remote false) should be absent
-    expect(cached["test-ga-flag"]).toBeUndefined();
+    // test-ga-flag (GA, remote false) should be normalized to true
+    expect(cached["test-ga-flag"]).toBe(true);
     // email-channel (gated, remote false) should be present
     expect(cached["email-channel"]).toBe(false);
     // test-ga-flag-true (unknown but true) should be present
@@ -498,6 +499,75 @@ describe("RemoteFeatureFlagSync", () => {
     expect(cached["unknown-flag"]).toBe(false);
   });
 
+  test("calls onChanged when remote flags change", async () => {
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: { "new-flag": true },
+      }),
+    );
+
+    const onChanged = mock(() => {});
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      onChanged,
+    });
+    await sync.start();
+    sync.stop();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(onChanged).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not call onChanged when remote flags have not changed", async () => {
+    // First sync to seed the file
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: { "stable-flag": true },
+      }),
+    );
+
+    const onChanged1 = mock(() => {});
+    const sync1 = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      onChanged: onChanged1,
+    });
+    await sync1.start();
+    sync1.stop();
+    expect(onChanged1).toHaveBeenCalledTimes(1);
+
+    // Second sync with same data — onChanged should NOT fire
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: { "stable-flag": true },
+      }),
+    );
+
+    const onChanged2 = mock(() => {});
+    const sync2 = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      onChanged: onChanged2,
+    });
+    await sync2.start();
+    sync2.stop();
+    expect(onChanged2).not.toHaveBeenCalled();
+  });
+
+  test("does not call onChanged on fetch failure", async () => {
+    fetchMock = mock(
+      async () => new Response("Internal Server Error", { status: 500 }),
+    );
+
+    const onChanged = mock(() => {});
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      onChanged,
+    });
+    await sync.start();
+    sync.stop();
+
+    expect(onChanged).not.toHaveBeenCalled();
+  });
+
   test("trims whitespace from credential values", async () => {
     fetchMock = mock(async () => Response.json({ flags: {} }));
 

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

@@ -173,6 +173,8 @@ const EXCLUDED_FROM_SCHEMA = new Set([
   "/v1/pair",
   // A2A agent card discovery — read-only, unauthenticated per spec
   "/.well-known/agent-card.json",
+  // Internal-only: reachable only via vembda's trusted gateway-query proxy
+  "/v1/contacts/guardian/channel",
 ]);
 
 // ── Schema paths that don't map to a discrete route definition ──