@vellumai/vellum-gateway 0.5.16 → 0.6.1

package/Dockerfile

@@ -1,5 +1,5 @@
 # Bun binary source (pinned to SHA digest for immutable reference)
-FROM oven/bun:1.2.21@sha256:5a2011bf09364b9af658ac1e66f60d08092f4291aeefbff448d58b027734fdd0 AS bun
+FROM oven/bun:1.3.11@sha256:0733e50325078969732ebe3b15ce4c4be5082f18c4ac1a0f0ca4839c2e4e42a7 AS bun
 
 # Build stage
 FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS builder

package/package.json

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

package/src/__tests__/config.test.ts

@@ -23,7 +23,8 @@ describe("config: hardcoded defaults", () => {
     expect(config.unmappedPolicy).toBe("reject");
     expect(config.routingEntries).toEqual([]);
     expect(config.defaultAssistantId).toBeUndefined();
-    expect(config.logFile).toEqual({ dir: undefined, retentionDays: 30 });
+    expect(config.logFile.dir).toMatch(/\.vellum\/logs$/);
+    expect(config.logFile.retentionDays).toBe(30);
   });
 
   test("GATEWAY_PORT defaults to 7830", () => {

package/src/__tests__/credential-watcher-managed-bootstrap.test.ts

@@ -221,4 +221,58 @@ describe("gateway managed credential bootstrap retry", () => {
 
     expect(status).toBe(401);
   }, 20_000);
+
+  test("detects new Slack credentials when metadata is written after startup with no initial channel services", async () => {
+    // Start with NO channel service metadata — only non-channel credentials
+    // (simulates a fresh assistant that has platform credentials but no channels).
+    mkdirSync(testDir, { recursive: true });
+    writeCredentialMetadata([
+      metadataRecord("api-key-1", "vellum", "assistant_api_key"),
+    ]);
+
+    startFakeCes({
+      credentials: {
+        "credential/vellum/assistant_api_key": "fake-api-key",
+        "credential/slack_channel/bot_token": "xoxb-fake-bot-token",
+        "credential/slack_channel/app_token": "xapp-fake-app-token",
+      },
+    });
+
+    await startGateway();
+
+    // Slack deliver should be 503 since no Slack credentials are configured.
+    const base = `http://localhost:${gatewayPort}`;
+    const before = await fetch(`${base}/deliver/slack`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+    });
+    expect(before.status).toBe(503);
+
+    // Now write Slack channel metadata (simulating the daemon storing
+    // credentials after the user completes the Slack setup flow).
+    writeCredentialMetadata([
+      metadataRecord("api-key-1", "vellum", "assistant_api_key"),
+      metadataRecord("bt-1", "slack_channel", "bot_token"),
+      metadataRecord("at-1", "slack_channel", "app_token"),
+    ]);
+
+    // The managed bootstrap retry should still be polling (since no channel
+    // services were configured at startup), so the new metadata should be
+    // detected within a few seconds even without fs.watch() working.
+    const deadline = Date.now() + 5_000;
+    let status = before.status;
+    while (Date.now() < deadline) {
+      const resp = await fetch(`${base}/deliver/slack`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+      });
+      status = resp.status;
+      // 401 means Slack is configured but the deliver auth check failed
+      // (which is expected since we didn't provide a valid bearer token).
+      if (status === 401) break;
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+
+    expect(status).toBe(401);
+  }, 20_000);
 });

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

@@ -39,11 +39,11 @@ const TEST_REGISTRY = {
       defaultEnabled: true,
     },
     {
-      id: "contacts",
+      id: "email-channel",
       scope: "assistant",
-      key: "contacts",
-      label: "Contacts",
-      description: "Contacts management",
+      key: "email-channel",
+      label: "Email Channel",
+      description: "Email channel integration",
       defaultEnabled: false,
     },
     {
@@ -262,19 +262,19 @@ describe("GET /v1/feature-flags handler", () => {
   });
 
   test("remote values fill in when no local override exists", async () => {
-    // Write a remote store with contacts enabled (overriding registry default of false)
+    // Write a remote store with email-channel enabled (overriding registry default of false)
     writeFileSync(
       remoteFeatureFlagStorePath,
       JSON.stringify({
         version: 1,
         values: {
-          contacts: true,
+          "email-channel": true,
         },
       }),
     );
     clearRemoteFeatureFlagStoreCache();
 
-    // No local override for contacts
+    // No local override for email-channel
     if (existsSync(featureFlagStorePath)) {
       rmSync(featureFlagStorePath);
     }
@@ -288,12 +288,12 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    const contactsFlag = body.flags.find(
-      (f: { key: string }) => f.key === "contacts",
+    const emailFlag = body.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
     );
-    expect(contactsFlag).toBeDefined();
+    expect(emailFlag).toBeDefined();
     // Remote value (true) overrides registry default (false)
-    expect(contactsFlag.enabled).toBe(true);
+    expect(emailFlag.enabled).toBe(true);
   });
 
   test("local overrides take precedence over remote values", async () => {
@@ -303,7 +303,7 @@ describe("GET /v1/feature-flags handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          contacts: true,
+          "email-channel": true,
         },
       }),
     );
@@ -315,7 +315,7 @@ describe("GET /v1/feature-flags handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          contacts: false,
+          "email-channel": false,
         },
       }),
     );
@@ -329,12 +329,12 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    const contactsFlag = body.flags.find(
-      (f: { key: string }) => f.key === "contacts",
+    const emailFlag = body.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
     );
-    expect(contactsFlag).toBeDefined();
+    expect(emailFlag).toBeDefined();
     // Local override (false) takes precedence over remote (true)
-    expect(contactsFlag.enabled).toBe(false);
+    expect(emailFlag.enabled).toBe(false);
   });
 
   test("registry default used when neither local nor remote is set", async () => {
@@ -358,13 +358,13 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    // contacts has defaultEnabled: false in registry
-    const contactsFlag = body.flags.find(
-      (f: { key: string }) => f.key === "contacts",
+    // email-channel has defaultEnabled: false in registry
+    const emailFlag = body.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
     );
-    expect(contactsFlag).toBeDefined();
-    expect(contactsFlag.enabled).toBe(false);
-    expect(contactsFlag.defaultEnabled).toBe(false);
+    expect(emailFlag).toBeDefined();
+    expect(emailFlag.enabled).toBe(false);
+    expect(emailFlag.defaultEnabled).toBe(false);
 
     // browser has defaultEnabled: true in registry
     const browserFlag = body.flags.find(
@@ -374,6 +374,34 @@ describe("GET /v1/feature-flags handler", () => {
     expect(browserFlag.enabled).toBe(true);
     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.
+    const handler = createFeatureFlagsGetHandler();
+    const res = await handler(
+      new Request(
+        "http://gateway.test/v1/assistants/some-assistant-id/feature-flags",
+      ),
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+
+    // Should return all assistant-scope flags with expected shape
+    expect(body.flags.length).toBeGreaterThan(0);
+    for (const flag of body.flags) {
+      expect(typeof flag.key).toBe("string");
+      expect(typeof flag.enabled).toBe("boolean");
+    }
+
+    // Verify a known flag is present
+    const browserFlag = body.flags.find(
+      (f: { key: string }) => f.key === "browser",
+    );
+    expect(browserFlag).toBeDefined();
+    expect(browserFlag.enabled).toBe(true);
+  });
 });
 
 describe("PATCH /v1/feature-flags/:flagKey handler", () => {
@@ -408,7 +436,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       JSON.stringify({
         version: 1,
         values: {
-          contacts: true,
+          "email-channel": true,
         },
       }),
     );
@@ -427,7 +455,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     // Both old and new values should be persisted
     clearFeatureFlagStoreCache();
     const persisted = readPersistedFeatureFlags();
-    expect(persisted["contacts"]).toBe(true);
+    expect(persisted["email-channel"]).toBe(true);
     expect(persisted["browser"]).toBe(true);
   });
 
@@ -543,7 +571,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
   test("accepts valid declared kebab-case key formats", async () => {
     const handler = createFeatureFlagsPatchHandler();
 
-    const validKeys = ["browser", "contacts"];
+    const validKeys = ["browser", "email-channel"];
 
     for (const key of validKeys) {
       clearFeatureFlagStoreCache();
@@ -614,7 +642,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       featureFlagStorePath,
       JSON.stringify({
         version: 1,
-        values: { contacts: true },
+        values: { "email-channel": true },
       }),
     );
     clearFeatureFlagStoreCache();
@@ -633,7 +661,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["contacts"]).toBe(true);
+    expect(data.values["email-channel"]).toBe(true);
     expect(data.values["browser"]).toBe(false);
 
     // Verify no temp files left behind
@@ -647,7 +675,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     const handler = createFeatureFlagsPatchHandler();
 
     // Fire multiple concurrent PATCH requests at the same time
-    const flagKeys = ["browser", "contacts"];
+    const flagKeys = ["browser", "email-channel"];
 
     const results = await Promise.all(
       flagKeys.map((key) =>

package/src/__tests__/remote-feature-flag-sync.test.ts

@@ -69,8 +69,17 @@ function defaultCredentials(): Record<string, string> {
 // ---------------------------------------------------------------------------
 // Setup / teardown
 // ---------------------------------------------------------------------------
+const savedVellumPlatformUrl = process.env.VELLUM_PLATFORM_URL;
+const savedPlatformAssistantId = process.env.PLATFORM_ASSISTANT_ID;
+const savedPlatformInternalApiKey = process.env.PLATFORM_INTERNAL_API_KEY;
+
 beforeEach(() => {
   process.env.BASE_DATA_DIR = testDir;
+  // Clear env vars that the production code falls back to, so tests remain
+  // deterministic unless they explicitly set them.
+  delete process.env.VELLUM_PLATFORM_URL;
+  delete process.env.PLATFORM_ASSISTANT_ID;
+  delete process.env.PLATFORM_INTERNAL_API_KEY;
   mkdirSync(protectedDir, { recursive: true });
   clearRemoteFeatureFlagStoreCache();
   fetchMock = mock(async () => new Response());
@@ -82,6 +91,17 @@ afterEach(() => {
   } else {
     process.env.BASE_DATA_DIR = savedBaseDataDir;
   }
+  // Restore env vars
+  const restoreEnv = (key: string, saved: string | undefined): void => {
+    if (saved === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = saved;
+    }
+  };
+  restoreEnv("VELLUM_PLATFORM_URL", savedVellumPlatformUrl);
+  restoreEnv("PLATFORM_ASSISTANT_ID", savedPlatformAssistantId);
+  restoreEnv("PLATFORM_INTERNAL_API_KEY", savedPlatformInternalApiKey);
   try {
     rmSync(testDir, { recursive: true, force: true });
   } catch {
@@ -94,7 +114,27 @@ afterEach(() => {
 // Tests
 // ---------------------------------------------------------------------------
 describe("RemoteFeatureFlagSync", () => {
-  test("skips sync when platform_base_url is missing", async () => {
+  test("skips sync when no platform URL is available from cache or env", async () => {
+    fetchMock = mock(async () => Response.json({ flags: { ff1: true } }));
+
+    const creds = defaultCredentials();
+    delete creds["credential/vellum/platform_base_url"];
+    delete process.env.VELLUM_PLATFORM_URL;
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(creds),
+    });
+    await sync.start();
+    sync.stop();
+
+    // No fetch calls — sync is skipped when platform URL is unavailable
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("falls back to VELLUM_PLATFORM_URL env var when platform_base_url is missing", async () => {
+    fetchMock = mock(async () => Response.json({ flags: {} }));
+    process.env.VELLUM_PLATFORM_URL = "https://env-platform.example.com";
+
     const creds = defaultCredentials();
     delete creds["credential/vellum/platform_base_url"];
 
@@ -104,10 +144,30 @@ describe("RemoteFeatureFlagSync", () => {
     await sync.start();
     sync.stop();
 
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url] = fetchMock.mock.calls[0];
+    expect(url).toBe(
+      "https://env-platform.example.com/v1/feature-flags/assistant-flag-values/",
+    );
+  });
+
+  test("skips sync when assistant_api_key is missing and no PLATFORM_INTERNAL_API_KEY", async () => {
+    const creds = defaultCredentials();
+    delete creds["credential/vellum/assistant_api_key"];
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(creds),
+    });
+    await sync.start();
+    sync.stop();
+
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
-  test("skips sync when assistant_api_key is missing", async () => {
+  test("does not use PLATFORM_INTERNAL_API_KEY when assistant_api_key is missing", async () => {
+    fetchMock = mock(async () => Response.json({ flags: {} }));
+    process.env.PLATFORM_INTERNAL_API_KEY = "internal-key-123";
+
     const creds = defaultCredentials();
     delete creds["credential/vellum/assistant_api_key"];
 
@@ -117,10 +177,12 @@ describe("RemoteFeatureFlagSync", () => {
     await sync.start();
     sync.stop();
 
+    // PLATFORM_INTERNAL_API_KEY is only for internal gateway endpoints —
+    // feature flag sync requires assistant_api_key (Api-Key auth).
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
-  test("skips sync when platform_assistant_id is missing", async () => {
+  test("skips sync when platform_assistant_id is missing and no PLATFORM_ASSISTANT_ID", async () => {
     const creds = defaultCredentials();
     delete creds["credential/vellum/platform_assistant_id"];
 
@@ -133,6 +195,24 @@ describe("RemoteFeatureFlagSync", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  test("falls back to PLATFORM_ASSISTANT_ID env var when credential cache is empty", async () => {
+    fetchMock = mock(async () => Response.json({ flags: {} }));
+    process.env.PLATFORM_ASSISTANT_ID = "env-asst-456";
+
+    const creds = defaultCredentials();
+    delete creds["credential/vellum/platform_assistant_id"];
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(creds),
+    });
+    await sync.start();
+    sync.stop();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url] = fetchMock.mock.calls[0];
+    expect(url).toContain("/v1/feature-flags/assistant-flag-values/");
+  });
+
   test("fetches and caches flags on successful response", async () => {
     fetchMock = mock(async () =>
       Response.json({
@@ -265,7 +345,7 @@ describe("RemoteFeatureFlagSync", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [url] = fetchMock.mock.calls[0];
     expect(url).toBe(
-      "https://platform.example.com/v1/assistants/asst-abc-999/feature-flags/",
+      "https://platform.example.com/v1/feature-flags/assistant-flag-values/",
     );
   });
 
@@ -344,10 +424,47 @@ describe("RemoteFeatureFlagSync", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [url] = fetchMock.mock.calls[0];
     expect(url).toBe(
-      "https://platform.example.com/v1/assistants/asst-123/feature-flags/",
+      "https://platform.example.com/v1/feature-flags/assistant-flag-values/",
     );
   });
 
+  test("ignores 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.
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: {
+          // GA flag (defaultEnabled: true) — remote false should be dropped
+          "conversation-starters": false,
+          // Gated flag (defaultEnabled: false) — remote false is kept
+          "email-channel": false,
+          // GA flag set to true — should be kept (redundant but harmless)
+          browser: true,
+          // Unknown flag — remote false is kept (not in registry)
+          "unknown-flag": false,
+        },
+      }),
+    );
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+    });
+    await sync.start();
+    sync.stop();
+
+    clearRemoteFeatureFlagStoreCache();
+    const cached = readRemoteFeatureFlags();
+    // conversation-starters (GA, remote false) should be absent
+    expect(cached["conversation-starters"]).toBeUndefined();
+    // email-channel (gated, remote false) should be present
+    expect(cached["email-channel"]).toBe(false);
+    // browser (GA, remote true) should be present
+    expect(cached.browser).toBe(true);
+    // unknown-flag (not in registry, remote false) should be present
+    expect(cached["unknown-flag"]).toBe(false);
+  });
+
   test("trims whitespace from credential values", async () => {
     fetchMock = mock(async () => Response.json({ flags: {} }));
 
@@ -365,7 +482,7 @@ describe("RemoteFeatureFlagSync", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [url, init] = fetchMock.mock.calls[0];
     expect(url).toBe(
-      "https://platform.example.com/v1/assistants/asst-trimmed/feature-flags/",
+      "https://platform.example.com/v1/feature-flags/assistant-flag-values/",
     );
     const headers = init?.headers as Record<string, string>;
     expect(headers.Authorization).toBe("Api-Key trimmed-key");

package/src/__tests__/telegram-webhook-manager.test.ts

@@ -293,6 +293,195 @@ describe("reconcileTelegramWebhook", () => {
     delete process.env.IS_CONTAINERIZED;
   });
 
+  test("registers via env vars when credential cache has no platform values", async () => {
+    const calls: {
+      method: string;
+      body: unknown;
+      headers?: Record<string, string>;
+    }[] = [];
+    process.env.IS_CONTAINERIZED = "true";
+    process.env.VELLUM_PLATFORM_URL = "https://env-platform.example.com";
+    process.env.PLATFORM_ASSISTANT_ID = "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee";
+    process.env.PLATFORM_INTERNAL_API_KEY = "internal-key-from-env";
+
+    const caches = makeCaches({
+      ingressUrl: undefined,
+      platformBaseUrl: undefined,
+      assistantApiKey: undefined,
+      platformAssistantId: undefined,
+    });
+
+    fetchMock = mock(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const url =
+          typeof input === "string"
+            ? input
+            : input instanceof URL
+              ? input.toString()
+              : input.url;
+        if (url.includes("/callback-routes/register/")) {
+          const body = init?.body ? JSON.parse(init.body as string) : null;
+          const headers = init?.headers as Record<string, string>;
+          calls.push({ method: "registerCallbackRoute", body, headers });
+          return new Response(
+            JSON.stringify({
+              callback_url:
+                "https://env-platform.example.com/v1/gateway/callbacks/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/webhooks/telegram/",
+            }),
+            {
+              status: 201,
+              headers: { "content-type": "application/json" },
+            },
+          );
+        }
+        if (url.includes("/getWebhookInfo")) {
+          calls.push({ method: "getWebhookInfo", body: null });
+          return makeTelegramResponse({
+            url: "",
+            has_custom_certificate: false,
+            pending_update_count: 0,
+          });
+        }
+        if (url.includes("/setWebhook")) {
+          const body = init?.body ? JSON.parse(init.body as string) : null;
+          calls.push({ method: "setWebhook", body });
+          return makeTelegramResponse(true);
+        }
+        return new Response("Not found", { status: 404 });
+      },
+    );
+
+    await reconcileTelegramWebhook(caches);
+
+    expect(calls).toHaveLength(3);
+    expect(calls[0].method).toBe("registerCallbackRoute");
+    expect(calls[0].body).toEqual({
+      assistant_id: "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
+      callback_path: "webhooks/telegram",
+      type: "telegram",
+    });
+    // PLATFORM_INTERNAL_API_KEY should use Bearer auth scheme
+    expect(calls[0].headers?.Authorization).toBe(
+      "Bearer internal-key-from-env",
+    );
+    expect(calls[2].method).toBe("setWebhook");
+    expect((calls[2].body as any).url).toBe(
+      "https://env-platform.example.com/v1/gateway/callbacks/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/webhooks/telegram/",
+    );
+
+    delete process.env.IS_CONTAINERIZED;
+    delete process.env.VELLUM_PLATFORM_URL;
+    delete process.env.PLATFORM_ASSISTANT_ID;
+    delete process.env.PLATFORM_INTERNAL_API_KEY;
+  });
+
+  test("env vars take precedence for auth key and assistant ID, cache for base URL", async () => {
+    const calls: {
+      method: string;
+      body: unknown;
+      headers?: Record<string, string>;
+    }[] = [];
+    process.env.IS_CONTAINERIZED = "true";
+    process.env.VELLUM_PLATFORM_URL = "https://env-platform.example.com";
+    process.env.PLATFORM_ASSISTANT_ID = "env-assistant-id";
+    process.env.PLATFORM_INTERNAL_API_KEY = "env-internal-key";
+
+    const caches = makeCaches({
+      ingressUrl: undefined,
+      platformBaseUrl: "https://cache-platform.example.com",
+      assistantApiKey: "cache-api-key",
+      platformAssistantId: "cache-assistant-id",
+    });
+
+    fetchMock = mock(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const url =
+          typeof input === "string"
+            ? input
+            : input instanceof URL
+              ? input.toString()
+              : input.url;
+        if (url.includes("/callback-routes/register/")) {
+          const body = init?.body ? JSON.parse(init.body as string) : null;
+          const headers = init?.headers as Record<string, string>;
+          calls.push({ method: "registerCallbackRoute", body, headers });
+          return new Response(
+            JSON.stringify({
+              callback_url:
+                "https://cache-platform.example.com/v1/gateway/callbacks/env-assistant-id/webhooks/telegram/",
+            }),
+            {
+              status: 201,
+              headers: { "content-type": "application/json" },
+            },
+          );
+        }
+        if (url.includes("/getWebhookInfo")) {
+          calls.push({ method: "getWebhookInfo", body: null });
+          return makeTelegramResponse({
+            url: "",
+            has_custom_certificate: false,
+            pending_update_count: 0,
+          });
+        }
+        if (url.includes("/setWebhook")) {
+          const body = init?.body ? JSON.parse(init.body as string) : null;
+          calls.push({ method: "setWebhook", body });
+          return makeTelegramResponse(true);
+        }
+        return new Response("Not found", { status: 404 });
+      },
+    );
+
+    await reconcileTelegramWebhook(caches);
+
+    expect(calls).toHaveLength(3);
+    expect(calls[0].method).toBe("registerCallbackRoute");
+    // platform_base_url: credential cache takes precedence over env var
+    // PLATFORM_ASSISTANT_ID and PLATFORM_INTERNAL_API_KEY: env var takes
+    // precedence, matching the daemon's resolvePlatformCallbackRegistrationContext().
+    expect(calls[0].body).toEqual({
+      assistant_id: "env-assistant-id",
+      callback_path: "webhooks/telegram",
+      type: "telegram",
+    });
+    expect(calls[0].headers?.Authorization).toBe("Bearer env-internal-key");
+    // Registration URL should use cache platform URL
+    expect((calls[2].body as any).url).toBe(
+      "https://cache-platform.example.com/v1/gateway/callbacks/env-assistant-id/webhooks/telegram/",
+    );
+
+    delete process.env.IS_CONTAINERIZED;
+    delete process.env.VELLUM_PLATFORM_URL;
+    delete process.env.PLATFORM_ASSISTANT_ID;
+    delete process.env.PLATFORM_INTERNAL_API_KEY;
+  });
+
+  test("skips registration when no platform URL is available from cache or env", async () => {
+    process.env.IS_CONTAINERIZED = "true";
+    process.env.PLATFORM_ASSISTANT_ID = "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee";
+    process.env.PLATFORM_INTERNAL_API_KEY = "internal-key-from-env";
+    delete process.env.VELLUM_PLATFORM_URL;
+
+    const caches = makeCaches({
+      ingressUrl: undefined,
+      platformBaseUrl: undefined,
+      assistantApiKey: undefined,
+      platformAssistantId: undefined,
+    });
+
+    fetchMock = mock(async () => new Response("", { status: 200 }));
+
+    await reconcileTelegramWebhook(caches);
+
+    // No fetch calls should be made — registration is skipped
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    delete process.env.IS_CONTAINERIZED;
+    delete process.env.PLATFORM_ASSISTANT_ID;
+    delete process.env.PLATFORM_INTERNAL_API_KEY;
+  });
+
   test("calls setWebhook when current URL is empty", async () => {
     const calls: string[] = [];