@vellumai/vellum-gateway 0.4.56 → 0.4.57

package/ARCHITECTURE.md

@@ -215,13 +215,13 @@ Channel readiness endpoints are exposed directly by the gateway and forwarded to
 
 ### Channel Binding Lifecycle (Lane Separation)
 
-Each channel (desktop, Telegram, etc.) operates in its own **lane**: conversations created by an external channel are never displayed in the desktop conversation list, and desktop conversations are never exposed to external channels. The `channelBinding` metadata on a conversation is used solely for routing inbound/outbound messages within that lane and for filtering sessions during desktop session restoration.
+Each channel (desktop, Telegram, etc.) operates in its own **lane**: conversations created by an external channel are never displayed in the desktop conversation list, and desktop conversations are never exposed to external channels. The `channelBinding` metadata on a conversation is used solely for routing inbound/outbound messages within that lane and for filtering conversations during desktop conversation restoration.
 
 Channel bindings follow a three-phase lifecycle:
 
 1. **Bind** — An inbound message from an external channel (e.g., Telegram chat) arrives at the gateway, which normalizes it and forwards it to the runtime's `/v1/channels/inbound` endpoint. The runtime creates or reuses a conversation, establishing the channel binding (`sourceChannel` metadata on the conversation).
 
-2. **Route** — Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Replies from the assistant are delivered back through the gateway's `/deliver/telegram` endpoint. The desktop client filters out channel-bound sessions during session restoration (`ConversationRestorer`) so they never appear in the desktop conversation list.
+2. **Route** — Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Replies from the assistant are delivered back through the gateway's `/deliver/telegram` endpoint. The desktop client filters out channel-bound conversations during conversation restoration (`ConversationRestorer`) so they never appear in the desktop conversation list.
 
 3. **Rebind** — If a message arrives on an external chat whose conversation was previously deleted, the channel inbound handler treats it as a new conversation and establishes a fresh binding. The external chat ID is reused, but the conversation is new.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.4.56",
+  "version": "0.4.57",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",

package/src/__tests__/config.test.ts

@@ -13,7 +13,7 @@ describe("config: hardcoded defaults", () => {
       telegram: 20 * 1024 * 1024,
       slack: 100 * 1024 * 1024,
       whatsapp: 16 * 1024 * 1024,
-      default: 50 * 1024 * 1024,
+      default: 100 * 1024 * 1024,
     });
     expect(config.maxAttachmentConcurrency).toBe(3);
     expect(config.runtimeProxyEnabled).toBe(false);

package/src/__tests__/credential-reader.test.ts

@@ -78,24 +78,16 @@ function getMachineEntropy(): string {
   return parts.join(":");
 }
 
-function writeEncryptedStore(entries: Record<string, string>): void {
-  const storePath = join(testDir, ".vellum", "protected", "keys.enc");
-  mkdirSync(join(testDir, ".vellum", "protected"), { recursive: true });
-
-  const salt = randomBytes(16);
-  const key = pbkdf2Sync(
-    getMachineEntropy(),
-    salt,
-    PBKDF2_ITERATIONS,
-    KEY_LENGTH,
-    "sha512",
-  );
+function encryptEntries(
+  entries: Record<string, string>,
+  key: Buffer,
+): Record<string, { iv: string; tag: string; data: string }> {
   const encryptedEntries: Record<
     string,
     { iv: string; tag: string; data: string }
   > = {};
   for (const [account, value] of Object.entries(entries)) {
-    const iv = randomBytes(12);
+    const iv = randomBytes(16);
     const cipher = createCipheriv(ALGORITHM, key, iv, {
       authTagLength: AUTH_TAG_LENGTH,
     });
@@ -110,15 +102,48 @@ function writeEncryptedStore(entries: Record<string, string>): void {
       data: encrypted.toString("hex"),
     };
   }
+  return encryptedEntries;
+}
+
+function writeEncryptedStore(entries: Record<string, string>): void {
+  const storePath = join(testDir, ".vellum", "protected", "keys.enc");
+  mkdirSync(join(testDir, ".vellum", "protected"), { recursive: true });
+
+  const salt = randomBytes(16);
+  const key = pbkdf2Sync(
+    getMachineEntropy(),
+    salt,
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    "sha512",
+  );
 
   const store = {
     version: 1,
     salt: salt.toString("hex"),
-    entries: encryptedEntries,
+    entries: encryptEntries(entries, key),
   };
   writeFileSync(storePath, JSON.stringify(store));
 }
 
+/**
+ * Write a v2 encrypted store with a random store.key file.
+ * The store.key is used directly as the AES-256-GCM key (no PBKDF2).
+ */
+function writeEncryptedStoreV2(entries: Record<string, string>): void {
+  const protectedDir = join(testDir, ".vellum", "protected");
+  mkdirSync(protectedDir, { recursive: true });
+
+  const storeKey = randomBytes(KEY_LENGTH);
+  writeFileSync(join(protectedDir, "store.key"), storeKey);
+
+  const store = {
+    version: 2,
+    entries: encryptEntries(entries, storeKey),
+  };
+  writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+}
+
 // ---------------------------------------------------------------------------
 // Broker test helpers — mock UDS server
 // ---------------------------------------------------------------------------
@@ -264,6 +289,74 @@ describe("readTelegramCredentials", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests: v2 encrypted store (store.key)
+// ---------------------------------------------------------------------------
+
+describe("v2 encrypted store with store.key", () => {
+  test("reads credential from v2 store when store.key exists", async () => {
+    writeEncryptedStoreV2({
+      [credentialKey("test", "key")]: "v2-secret-value",
+    });
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBe("v2-secret-value");
+  });
+
+  test("returns undefined for v2 store when store.key is missing", async () => {
+    // Write a v2 store but without the store.key file
+    const protectedDir = join(testDir, ".vellum", "protected");
+    mkdirSync(protectedDir, { recursive: true });
+
+    const storeKey = randomBytes(KEY_LENGTH);
+    const store = {
+      version: 2,
+      entries: encryptEntries(
+        { [credentialKey("test", "key")]: "v2-secret-value" },
+        storeKey,
+      ),
+    };
+    writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+    // Deliberately do NOT write store.key
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBeUndefined();
+  });
+
+  test("returns Telegram credentials from v2 store", async () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    writeEncryptedStoreV2({
+      [credentialKey("telegram", "bot_token")]: "v2-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "v2-webhook-secret",
+    });
+
+    const result = await readTelegramCredentials();
+    expect(result).toEqual({
+      botToken: "v2-bot-token",
+      webhookSecret: "v2-webhook-secret",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: v1 encrypted store backward compatibility
+// ---------------------------------------------------------------------------
+
+describe("v1 encrypted store backward compatibility", () => {
+  test("v1 store continues to work with entropy-based key derivation", async () => {
+    writeEncryptedStore({
+      [credentialKey("test", "key")]: "v1-secret-value",
+    });
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBe("v1-secret-value");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests: broker credential reading
 // ---------------------------------------------------------------------------

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

@@ -68,7 +68,7 @@ function encrypt(
   value: string,
   key: Buffer,
 ): { iv: string; tag: string; data: string } {
-  const iv = cryptoRandomBytes(12);
+  const iv = cryptoRandomBytes(16);
   const cipher = createCipheriv(ALGORITHM, key, iv, {
     authTagLength: AUTH_TAG_LENGTH,
   });
@@ -114,6 +114,31 @@ function writeEncryptedStore(botToken: string, webhookSecret: string): void {
   writeFileSync(storePath, JSON.stringify(store));
 }
 
+/**
+ * Write Telegram credentials into a v2 encrypted store using a random
+ * store.key file (no PBKDF2 derivation).
+ */
+function writeEncryptedStoreV2(
+  botToken: string,
+  webhookSecret: string,
+): void {
+  const protectedDir = join(testDir, ".vellum", "protected");
+  mkdirSync(protectedDir, { recursive: true });
+
+  const storeKey = cryptoRandomBytes(KEY_LENGTH);
+  writeFileSync(join(protectedDir, "store.key"), storeKey);
+
+  const store = {
+    version: 2,
+    entries: {
+      "credential/telegram/bot_token": encrypt(botToken, storeKey),
+      "credential/telegram/webhook_secret": encrypt(webhookSecret, storeKey),
+    },
+  };
+
+  writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+}
+
 function metadataRecord(
   credentialId: string,
   service: string,
@@ -289,4 +314,38 @@ describe("gateway telegram hot-reload (e2e)", () => {
     });
     expect(after.status).toBe(401);
   }, 15_000);
+
+  test("gateway hot-reloads v2 encrypted store credentials written after startup", async () => {
+    // --- Setup: no credentials directory exists (fresh hatch) ---
+    mkdirSync(testDir, { recursive: true });
+
+    // Start the real gateway process
+    await startGateway();
+
+    const base = `http://localhost:${port}`;
+
+    // --- Step 1: confirm Telegram is NOT configured ---
+    const before = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(before.status).toBe(503);
+    const beforeBody = (await before.json()) as { error: string };
+    expect(beforeBody.error).toBe("Telegram integration not configured");
+
+    // --- Step 2: simulate daemon writing v2 credentials ---
+    writeEncryptedStoreV2("fake-v2-bot-token:XYZ", "fake-v2-webhook-secret");
+    writeCredentialMetadata();
+
+    // Wait for credential watcher debounce (500ms) + generous margin
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // --- Step 3: query again — gateway should now recognize Telegram is configured.
+    // We expect 401 (webhook secret verification failed) rather than 503
+    // (not configured). Getting past the 503 gate proves the gateway
+    // hot-reloaded the v2 credentials from the credential store.
+    const after = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(after.status).toBe(401);
+  }, 15_000);
 });

package/src/__tests__/sleep-wake-detector.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test, mock, beforeEach, afterEach } from "bun:test";
+import { SleepWakeDetector } from "../sleep-wake-detector.js";
+
+// Suppress logger output during tests
+mock.module("../logger.js", () => ({
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+  initLogger: () => {},
+}));
+
+describe("SleepWakeDetector", () => {
+  let detector: SleepWakeDetector;
+  let onWake: ReturnType<typeof mock>;
+  let originalDateNow: () => number;
+  let fakeNow: number;
+
+  beforeEach(() => {
+    onWake = mock(() => {});
+    originalDateNow = Date.now;
+    fakeNow = 1000000;
+    Date.now = () => fakeNow;
+  });
+
+  afterEach(() => {
+    detector?.stop();
+    Date.now = originalDateNow;
+  });
+
+  test("does not fire callback on normal ticks", async () => {
+    detector = new SleepWakeDetector(onWake, 50, 2);
+    detector.start();
+
+    // Advance time normally (within threshold)
+    fakeNow += 55;
+    await new Promise((r) => setTimeout(r, 70));
+
+    expect(onWake).not.toHaveBeenCalled();
+  });
+
+  test("fires callback when elapsed time exceeds threshold", async () => {
+    detector = new SleepWakeDetector(onWake, 50, 2);
+    detector.start();
+
+    // Wait for first tick at normal time
+    await new Promise((r) => setTimeout(r, 60));
+
+    // Simulate a sleep gap: jump time forward well past the threshold
+    fakeNow += 200; // 4x the interval
+
+    // Wait for next tick
+    await new Promise((r) => setTimeout(r, 60));
+
+    expect(onWake).toHaveBeenCalledTimes(1);
+  });
+
+  test("stop prevents further callbacks", async () => {
+    detector = new SleepWakeDetector(onWake, 50, 2);
+    detector.start();
+    detector.stop();
+
+    fakeNow += 500;
+    await new Promise((r) => setTimeout(r, 70));
+
+    expect(onWake).not.toHaveBeenCalled();
+  });
+
+  test("start after stop resets cleanly", async () => {
+    detector = new SleepWakeDetector(onWake, 50, 2);
+    detector.start();
+    detector.stop();
+    detector.start();
+
+    // Normal tick — should not fire
+    fakeNow += 55;
+    await new Promise((r) => setTimeout(r, 70));
+
+    expect(onWake).not.toHaveBeenCalled();
+  });
+});

package/src/config.ts

@@ -98,7 +98,9 @@ export function loadConfig(): GatewayConfig {
   const gw = (wsConfig.gateway ?? {}) as Record<string, unknown>;
 
   const runtimeProxyEnabled =
-    gw.runtimeProxyEnabled === true || gw.runtimeProxyEnabled === "true";
+    gw.runtimeProxyEnabled === true ||
+    gw.runtimeProxyEnabled === "true" ||
+    process.env.RUNTIME_PROXY_ENABLED === "true";
   const runtimeProxyRequireAuth =
     gw.runtimeProxyRequireAuth !== false &&
     gw.runtimeProxyRequireAuth !== "false";
@@ -138,7 +140,7 @@ export function loadConfig(): GatewayConfig {
       telegram: 20 * 1024 * 1024, // Telegram Bot API getFile limit
       slack: 100 * 1024 * 1024, // Slack standard plan
       whatsapp: 16 * 1024 * 1024, // WhatsApp Business API limit
-      default: 50 * 1024 * 1024, // Fallback; capped by runtime MAX_UPLOAD_BYTES (50 MB)
+      default: 100 * 1024 * 1024, // Fallback; capped by runtime MAX_UPLOAD_BYTES (100 MB)
     },
     maxAttachmentConcurrency: 3,
     maxWebhookPayloadBytes: 1024 * 1024,

package/src/credential-reader.ts

@@ -26,12 +26,21 @@ interface EncryptedEntry {
   data: string;
 }
 
-interface StoreFile {
+interface StoreFileV1 {
   version: 1;
   salt: string;
   entries: Record<string, EncryptedEntry>;
 }
 
+interface StoreFileV2 {
+  version: 2;
+  entries: Record<string, EncryptedEntry>;
+}
+
+type StoreFile = StoreFileV1 | StoreFileV2;
+
+const STORE_KEY_FILENAME = "store.key";
+
 function getPlatformName(): string {
   // Must match assistant/src/util/platform.ts#getPlatformName exactly.
   // Using user-friendly labels like "macOS" here changes PBKDF2 entropy and
@@ -66,6 +75,22 @@ function deriveKey(salt: Buffer): Buffer {
   return pbkdf2Sync(entropy, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
 }
 
+/**
+ * Read the v2 store key file (~/.vellum/protected/store.key).
+ * Returns null if the file doesn't exist or isn't exactly 32 bytes.
+ */
+function readStoreKey(): Buffer | null {
+  const keyPath = join(getRootDir(), "protected", STORE_KEY_FILENAME);
+  if (!existsSync(keyPath)) return null;
+  try {
+    const buf = readFileSync(keyPath);
+    if (buf.length !== KEY_LENGTH) return null;
+    return buf;
+  } catch {
+    return null;
+  }
+}
+
 function decrypt(entry: EncryptedEntry, key: Buffer): string {
   const iv = Buffer.from(entry.iv, "hex");
   const tag = Buffer.from(entry.tag, "hex");
@@ -83,17 +108,26 @@ function readStore(storePath: string): StoreFile | null {
 
   const raw = readFileSync(storePath, "utf-8");
   const parsed = JSON.parse(raw);
+
+  if (parsed.version === 2 && typeof parsed.entries === "object") {
+    const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+    Object.assign(safeEntries, parsed.entries);
+    parsed.entries = safeEntries;
+    return parsed as StoreFileV2;
+  }
+
   if (
-    parsed.version !== 1 ||
-    typeof parsed.salt !== "string" ||
-    typeof parsed.entries !== "object"
+    parsed.version === 1 &&
+    typeof parsed.salt === "string" &&
+    typeof parsed.entries === "object"
   ) {
-    throw new Error("Encrypted store has invalid format");
+    const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+    Object.assign(safeEntries, parsed.entries);
+    parsed.entries = safeEntries;
+    return parsed as StoreFileV1;
   }
-  const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
-  Object.assign(safeEntries, parsed.entries);
-  parsed.entries = safeEntries;
-  return parsed as StoreFile;
+
+  throw new Error("Encrypted store has invalid format");
 }
 
 export function getRootDir(): string {
@@ -125,6 +159,9 @@ export function getMetadataPath(): string {
  * Read a single credential from the encrypted store.
  * Returns `undefined` if the store doesn't exist, the key is missing,
  * or decryption fails.
+ *
+ * For v2 stores, uses the store.key file directly as the AES key.
+ * For v1 stores, derives the key from machine entropy via PBKDF2.
  */
 function readEncryptedCredential(account: string): string | undefined {
   try {
@@ -134,8 +171,15 @@ function readEncryptedCredential(account: string): string | undefined {
     const entry = store.entries[account];
     if (!entry) return undefined;
 
-    const salt = Buffer.from(store.salt, "hex");
-    const key = deriveKey(salt);
+    let key: Buffer;
+    if (store.version === 2) {
+      const storeKey = readStoreKey();
+      if (!storeKey) return undefined;
+      key = storeKey;
+    } else {
+      const salt = Buffer.from(store.salt, "hex");
+      key = deriveKey(salt);
+    }
     return decrypt(entry, key);
   } catch (err) {
     log.debug({ err, account }, "Failed to read from encrypted store");

package/src/credential-watcher.ts

@@ -1,19 +1,20 @@
 /**
- * Watches the assistant's credential metadata file for changes and
- * triggers a callback when Telegram or Twilio credentials are added,
+ * Watches the assistant's credential metadata file and the v2 store key
+ * for changes, triggering a callback when channel credentials are added,
  * updated, or removed.
  *
- * Watches the parent directory rather than the file itself because
+ * Watches parent directories rather than files themselves because
  * metadata.json is rewritten via atomic rename. File-scoped fs.watch()
  * subscriptions can stay attached to the old inode after the first write,
  * causing later credential changes to be missed until restart.
  */
 
 import { mkdirSync, watch, type FSWatcher } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { getLogger } from "./logger.js";
 import {
   getMetadataPath,
+  getRootDir,
   readTelegramCredentials,
   readTwilioCredentials,
   readWhatsAppCredentials,
@@ -42,7 +43,7 @@ export type CredentialChangeEvent = {
 export type CredentialChangeCallback = (event: CredentialChangeEvent) => void;
 
 export class CredentialWatcher {
-  private watcher: FSWatcher | null = null;
+  private watchers: FSWatcher[] = [];
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
   private lastSerialized: Map<string, string> = new Map();
   private polling = false;
@@ -58,28 +59,43 @@ export class CredentialWatcher {
   async start(): Promise<void> {
     await this.pollOnce();
 
-    const watchTarget = dirname(this.metadataPath);
+    const metadataDir = dirname(this.metadataPath);
+    const protectedDir = join(getRootDir(), "protected");
 
-    // Ensure the directory exists so fs.watch() doesn't throw ENOENT
+    // Ensure directories exist so fs.watch() doesn't throw ENOENT
     // on a fresh hatch where no credentials have been written yet.
-    mkdirSync(watchTarget, { recursive: true });
+    mkdirSync(metadataDir, { recursive: true });
+    mkdirSync(protectedDir, { recursive: true });
 
+    // Watch the metadata directory for metadata.json changes.
+    this.startWatcher(metadataDir, "metadata.json");
+
+    // Watch the protected directory for store.key changes so that
+    // creating or restoring the v2 store key triggers a credential reload.
+    this.startWatcher(protectedDir, "store.key");
+  }
+
+  private startWatcher(dir: string, targetFilename: string): void {
     try {
-      this.watcher = watch(
-        watchTarget,
+      const watcher = watch(
+        dir,
         { persistent: false },
         (_event, filename) => {
-          if (filename && filename !== "metadata.json") {
+          if (filename && filename !== targetFilename) {
             return;
           }
           this.scheduleCheck();
         },
       );
+      this.watchers.push(watcher);
 
-      log.info({ path: watchTarget }, "Watching for credential changes");
+      log.info(
+        { path: dir, file: targetFilename },
+        "Watching for credential changes",
+      );
     } catch (err) {
       log.warn(
-        { err, path: watchTarget },
+        { err, path: dir },
         "Failed to start credential file watcher",
       );
     }
@@ -91,10 +107,10 @@ export class CredentialWatcher {
       this.debounceTimer = null;
     }
     this.pendingPoll = false;
-    if (this.watcher) {
-      this.watcher.close();
-      this.watcher = null;
+    for (const watcher of this.watchers) {
+      watcher.close();
     }
+    this.watchers = [];
   }
 
   private scheduleCheck(): void {

package/src/feature-flag-registry.json

@@ -41,14 +41,6 @@
       "description": "Enable multi-file TSX app creation with esbuild compilation instead of single-HTML apps",
       "defaultEnabled": false
     },
-    {
-      "id": "sentry-testing",
-      "scope": "macos",
-      "key": "sentry_testing_enabled",
-      "label": "Sentry Testing",
-      "description": "Show the Sentry Testing tab in Settings for triggering test crash reports and error events",
-      "defaultEnabled": false
-    },
     {
       "id": "mobile-pairing",
       "scope": "macos",
@@ -226,19 +218,43 @@
       "defaultEnabled": false
     },
     {
-      "id": "thread-starters",
-      "scope": "macos",
-      "key": "thread_starters_enabled",
-      "label": "Thread Starters",
-      "description": "Show personalized thread starter suggestions on the empty conversation page",
+      "id": "integration-notion",
+      "scope": "assistant",
+      "key": "feature_flags.integration-notion.enabled",
+      "label": "Notion Integration",
+      "description": "Enable the Notion setup skill for connecting to Notion",
+      "defaultEnabled": false
+    },
+    {
+      "id": "conversation-starters",
+      "scope": "assistant",
+      "key": "feature_flags.conversation-starters.enabled",
+      "label": "Recommended Starts",
+      "description": "Show a curated row of recommended starting actions on the empty conversation page, ordered by relevance as confident first-click options",
+      "defaultEnabled": true
+    },
+    {
+      "id": "deploy-to-vercel",
+      "scope": "assistant",
+      "key": "feature_flags.deploy-to-vercel.enabled",
+      "label": "Deploy to Vercel",
+      "description": "Enable the Deploy to Vercel / Publish option in the app workspace header share menu",
+      "defaultEnabled": false
+    },
+    {
+      "id": "managed-google-oauth",
+      "scope": "assistant",
+      "key": "feature_flags.managed-google-oauth.enabled",
+      "label": "Managed Google OAuth",
+      "description": "Show the Google OAuth service card in Models & Services settings",
       "defaultEnabled": false
     },
     {
-      "id": "capability-feed",
+      "id": "quick-input",
       "scope": "macos",
-      "key": "capability_feed_enabled",
-      "label": "Capability Feed",
-      "description": "Show the scrollable capability cards feed below the hero on the new thread page",
+      "key": "quick_input_enabled",
+      "label": "Quick Input",
+      "description": "Enable the Quick Input popover on right-click of the menu bar icon",
       "defaultEnabled": false
     }
   ]

package/src/index.ts

@@ -67,6 +67,7 @@ import {
   type RouteDefinition,
   type GetClientIp,
 } from "./http/router.js";
+import { SleepWakeDetector } from "./sleep-wake-detector.js";
 import { callTelegramApi } from "./telegram/api.js";
 import { reconcileTelegramWebhook } from "./telegram/webhook-manager.js";
 
@@ -663,6 +664,13 @@ async function main() {
         channelReadinessProxy.handleRefreshChannelReadiness(req),
     },
 
+    {
+      path: /^\/v1\/assistants\/([^/]+)\/channels\/readiness\/$/,
+      method: "GET",
+      auth: "edge",
+      handler: (req) => channelReadinessProxy.handleGetChannelReadiness(req),
+    },
+
     // ── Integration status ──
     {
       path: "/integrations/status",
@@ -675,6 +683,17 @@ async function main() {
           },
         }),
     },
+    {
+      path: /^\/v1\/assistants\/([^/]+)\/integrations\/status\/$/,
+      method: "GET",
+      auth: "edge",
+      handler: () =>
+        Response.json({
+          email: {
+            address: configFileCache.getString("email", "address") ?? null,
+          },
+        }),
+    },
 
     // ── Feature flags (scope-protected) ──
     {
@@ -684,6 +703,13 @@ async function main() {
       scope: "feature_flags.read",
       handler: (req) => handleFeatureFlagsGet(req),
     },
+    {
+      path: /^\/v1\/assistants\/([^/]+)\/feature-flags\/$/,
+      method: "GET",
+      auth: "edge-scoped",
+      scope: "feature_flags.read",
+      handler: (req) => handleFeatureFlagsGet(req),
+    },
     {
       path: /^\/v1\/feature-flags\/(.+)$/,
       method: "PATCH",
@@ -702,6 +728,24 @@ async function main() {
         return handleFeatureFlagsPatch(req, flagKey);
       },
     },
+    {
+      path: /^\/v1\/assistants\/([^/]+)\/feature-flags\/(.+)$/,
+      method: "PATCH",
+      auth: "edge-scoped",
+      scope: "feature_flags.write",
+      handler: (req, params) => {
+        let flagKey: string;
+        try {
+          flagKey = decodeURIComponent(params[1].replace(/\/$/, ""));
+        } catch {
+          return Response.json(
+            { error: "Invalid flag key encoding" },
+            { status: 400 },
+          );
+        }
+        return handleFeatureFlagsPatch(req, flagKey);
+      },
+    },
 
     // ── Privacy config (scope-protected) ──
     {
@@ -711,6 +755,13 @@ async function main() {
       scope: "settings.write",
       handler: (req) => handlePrivacyConfigPatch(req),
     },
+    {
+      path: /^\/v1\/assistants\/([^/]+)\/config\/privacy\/$/,
+      method: "PATCH",
+      auth: "edge-scoped",
+      scope: "settings.write",
+      handler: (req) => handlePrivacyConfigPatch(req),
+    },
   ];
 
   // The runtime proxy catch-all is only added when the proxy is enabled.
@@ -785,6 +836,25 @@ async function main() {
         if (draining) {
           return Response.json({ status: "draining" }, { status: 503 });
         }
+        // Check that the upstream assistant is also reachable so callers
+        // know the full stack is ready, not just the gateway process.
+        try {
+          const upstream = await fetch(
+            `${config.assistantRuntimeBaseUrl}/healthz`,
+            { signal: AbortSignal.timeout(3000) },
+          );
+          if (!upstream.ok) {
+            return Response.json(
+              { status: "upstream_unhealthy", upstream: upstream.status },
+              { status: 503 },
+            );
+          }
+        } catch {
+          return Response.json(
+            { status: "upstream_unreachable" },
+            { status: 503 },
+          );
+        }
         return Response.json({ status: "ok" });
       }
 
@@ -983,11 +1053,34 @@ async function main() {
 
   configFileWatcher.start();
 
+  // ── Sleep/wake detection ──
+  // Detect system sleep/wake transitions and force-reconnect channels
+  // that may have stale connections after the OS suspended the process.
+  const sleepWakeDetector = new SleepWakeDetector(() => {
+    log.info("System wake detected — reconnecting channels");
+
+    // Force-reconnect Slack WebSocket (may be half-open after sleep)
+    slackSocketClient?.forceReconnect();
+
+    // Invalidate caches so next read picks up any config changes (e.g. new ngrok URL)
+    configFileCache.invalidate();
+    credentialCache.invalidate();
+
+    // Re-register Telegram webhook with current ingress URL
+    if (telegramReady) {
+      reconcileTelegramWebhook(telegramCaches).catch((err) => {
+        log.error({ err }, "Failed to reconcile Telegram webhook after wake");
+      });
+    }
+  });
+  sleepWakeDetector.start();
+
   const drainMs = config.shutdownDrainMs;
 
   process.on("SIGTERM", () => {
     log.info("SIGTERM received, starting graceful shutdown");
     draining = true;
+    sleepWakeDetector.stop();
     credentialWatcher.stop();
     configFileWatcher.stop();
     telegramDedupCache.stopCleanup();

package/src/schema.ts

@@ -1633,6 +1633,32 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/assistants/{assistantId}/channels/readiness/": {
+        get: {
+          summary: "Get channel readiness (scoped)",
+          description:
+            "Authenticated gateway endpoint that returns the readiness status of all configured channels from the assistant runtime. The assistantId path segment is used for routing but does not affect the response.",
+          operationId: "channelReadinessScopedGet",
+          parameters: [
+            {
+              name: "assistantId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": { description: "Channel readiness status returned" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
       "/v1/channels/readiness/refresh": {
         post: {
           summary: "Refresh channel readiness",
@@ -1758,6 +1784,130 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/assistants/{assistantId}/feature-flags/": {
+        get: {
+          summary: "List feature flags (assistant-scoped)",
+          description:
+            "Assistant-scoped variant of the feature flags endpoint. Requires a bearer token with `feature_flags.read` scope.",
+          operationId: "assistantFeatureFlagsGet",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "assistantId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The assistant identifier.",
+            },
+          ],
+          responses: {
+            "200": { description: "Feature flags returned" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "403": { description: "Insufficient scope" },
+          },
+        },
+      },
+      "/v1/assistants/{assistantId}/feature-flags/{flagKey}": {
+        patch: {
+          summary: "Update a feature flag (assistant-scoped)",
+          description:
+            "Assistant-scoped variant of the feature flag update endpoint. Requires a bearer token with `feature_flags.write` scope.",
+          operationId: "assistantFeatureFlagsPatch",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "assistantId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The assistant identifier.",
+            },
+            {
+              name: "flagKey",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The feature flag key to update.",
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Feature flag updated" },
+            "400": { description: "Invalid flag key encoding" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "403": { description: "Insufficient scope" },
+          },
+        },
+      },
+      "/v1/assistants/{assistantId}/config/privacy/": {
+        patch: {
+          summary: "Update privacy config (assistant-scoped)",
+          description:
+            "Assistant-scoped variant of the privacy config endpoint. Requires a bearer token with `settings.write` scope.",
+          operationId: "assistantPrivacyConfigPatch",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "assistantId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The assistant identifier.",
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    collectUsageData: { type: "boolean" },
+                    sendDiagnostics: { type: "boolean" },
+                  },
+                  anyOf: [
+                    { required: ["collectUsageData"] },
+                    { required: ["sendDiagnostics"] },
+                  ],
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Privacy config updated",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      collectUsageData: { type: "boolean" },
+                      sendDiagnostics: { type: "boolean" },
+                    },
+                  },
+                },
+              },
+            },
+            "400": { description: "Invalid request body" },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "403": { description: "Insufficient scope" },
+            "500": { description: "Internal server error" },
+          },
+        },
+      },
       "/integrations/status": {
         get: {
           summary: "Integration status",
@@ -1795,6 +1945,51 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/assistants/{assistantId}/integrations/status/": {
+        get: {
+          summary: "Integration status (scoped)",
+          description:
+            "Returns the current status of configured integrations, including the assistant's email address. Requires a valid bearer token. The assistantId path segment is used for routing but does not affect the response.",
+          operationId: "integrationsStatusScoped",
+          parameters: [
+            {
+              name: "assistantId",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Integration status",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/IntegrationsStatusResponse",
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "503": {
+              description: "Bearer token not configured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
       "/deliver/telegram": {
         post: {
           summary: "Telegram delivery (internal)",

package/src/slack/socket-mode.ts

@@ -51,6 +51,7 @@ export class SlackSocketModeClient {
   private config: SlackSocketModeConfig;
   private onEvent: (event: NormalizedSlackEvent) => void;
   private ws: WebSocket | null = null;
+  private connecting = false;
   private running = false;
   private reconnectAttempt = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
@@ -133,6 +134,7 @@ export class SlackSocketModeClient {
 
   stop(): void {
     this.running = false;
+    this.connecting = false;
     this.stopDedupCleanup();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -148,6 +150,89 @@ export class SlackSocketModeClient {
     }
   }
 
+  /**
+   * Force-close the current WebSocket and reconnect immediately.
+   * Used by the sleep/wake detector to recover from half-open connections
+   * that survive system sleep.
+   *
+   * Waits for the old socket to fully close before connecting a new one
+   * to prevent overlapping connections where stale message events could
+   * be ACKed on the wrong socket.
+   */
+  forceReconnect(): void {
+    if (!this.running) return;
+
+    log.info("Force-reconnecting Slack Socket Mode (sleep/wake recovery)");
+
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    this.reconnectAttempt = 0;
+
+    const oldWs = this.ws;
+    this.ws = null;
+
+    // If a connect() call is already in-flight (awaiting getWebSocketUrl),
+    // don't start another one — the in-flight attempt will complete and
+    // establish a fresh connection. We still tear down the old socket and
+    // cancel the reconnect timer above so there's no stale state.
+    if (this.connecting) {
+      log.info(
+        "Connect already in-flight, skipping duplicate — tearing down old socket only",
+      );
+      if (oldWs) {
+        try {
+          oldWs.close(1000, "force reconnect");
+        } catch {
+          // ignore
+        }
+      }
+      return;
+    }
+
+    if (!oldWs || oldWs.readyState === WebSocket.CLOSED) {
+      this.connect().catch((err) => {
+        log.error({ err }, "Force reconnect failed");
+      });
+      return;
+    }
+
+    // Wait for the old socket to fully close before opening a new one.
+    // Use a timeout to avoid blocking indefinitely on half-open sockets
+    // that may never emit a close event (the exact scenario that triggers
+    // a force reconnect after sleep).
+    const CLOSE_TIMEOUT_MS = 5_000;
+    let settled = false;
+
+    const proceed = () => {
+      if (settled) return;
+      settled = true;
+      this.connect().catch((err) => {
+        log.error({ err }, "Force reconnect failed");
+      });
+    };
+
+    oldWs.addEventListener("close", proceed, { once: true });
+
+    setTimeout(() => {
+      if (!settled) {
+        log.warn(
+          "Old Slack socket did not close within timeout, proceeding with reconnect",
+        );
+        proceed();
+      }
+    }, CLOSE_TIMEOUT_MS);
+
+    try {
+      oldWs.close(1000, "force reconnect");
+    } catch {
+      // Socket may already be in a broken state — proceed immediately
+      proceed();
+    }
+  }
+
   /**
    * Register a thread as active so future replies (without @mention) are forwarded.
    */
@@ -157,12 +242,15 @@ export class SlackSocketModeClient {
 
   private async connect(): Promise<void> {
     if (!this.running) return;
+    if (this.connecting) return;
+    this.connecting = true;
 
     let wsUrl: string;
     try {
       wsUrl = await this.getWebSocketUrl();
     } catch (err) {
       log.error({ err }, "Failed to obtain Socket Mode WebSocket URL");
+      this.connecting = false;
       this.scheduleReconnect();
       return;
     }
@@ -172,6 +260,7 @@ export class SlackSocketModeClient {
     try {
       const ws = new WebSocket(wsUrl);
       this.ws = ws;
+      this.connecting = false;
 
       ws.addEventListener("open", () => {
         log.info("Slack Socket Mode connected");
@@ -179,7 +268,7 @@ export class SlackSocketModeClient {
       });
 
       ws.addEventListener("message", (messageEvent) => {
-        this.handleMessage(messageEvent.data as string);
+        this.handleMessage(messageEvent.data as string, ws);
       });
 
       ws.addEventListener("close", (closeEvent) => {
@@ -187,8 +276,13 @@ export class SlackSocketModeClient {
           { code: closeEvent.code, reason: closeEvent.reason },
           "Slack Socket Mode disconnected",
         );
-        this.ws = null;
-        this.scheduleReconnect();
+        // Only reconnect if this socket is still the active one.
+        // forceReconnect nulls this.ws before initiating a new connection,
+        // so a stale close event should be ignored.
+        if (this.ws === ws) {
+          this.ws = null;
+          this.scheduleReconnect();
+        }
       });
 
       ws.addEventListener("error", (errorEvent) => {
@@ -200,6 +294,7 @@ export class SlackSocketModeClient {
     } catch (err) {
       log.error({ err }, "Failed to create WebSocket connection");
       this.ws = null;
+      this.connecting = false;
       this.scheduleReconnect();
     }
   }
@@ -242,7 +337,7 @@ export class SlackSocketModeClient {
     };
   }
 
-  private handleMessage(raw: string): void {
+  private handleMessage(raw: string, originWs: WebSocket): void {
     let envelope: {
       envelope_id?: string;
       type?: string;
@@ -272,32 +367,31 @@ export class SlackSocketModeClient {
       return;
     }
 
-    // ACK every envelope immediately
-    if (
-      envelope.envelope_id &&
-      this.ws &&
-      this.ws.readyState === WebSocket.OPEN
-    ) {
-      this.ws.send(JSON.stringify({ envelope_id: envelope.envelope_id }));
+    // ACK every envelope on the socket that received it — never cross-ACK
+    // onto a different connection (e.g. after forceReconnect replaces this.ws).
+    if (envelope.envelope_id && originWs.readyState === WebSocket.OPEN) {
+      originWs.send(JSON.stringify({ envelope_id: envelope.envelope_id }));
     }
 
-    // Handle disconnect type: Slack asks us to reconnect
+    // Handle disconnect type: Slack asks us to reconnect.
+    // Only act if the requesting socket is still the active one —
+    // a stale socket's disconnect should not tear down a new connection.
     if (envelope.type === "disconnect") {
       log.info(
         { reason: envelope.reason },
         "Slack requested disconnect, reconnecting",
       );
-      if (this.ws) {
+      if (this.ws === originWs) {
         try {
           this.ws.close(1000, "server requested disconnect");
         } catch {
           // ignore
         }
         this.ws = null;
+        // Reconnect immediately (attempt 0 = minimal backoff)
+        this.reconnectAttempt = 0;
+        this.scheduleReconnect();
       }
-      // Reconnect immediately (attempt 0 = minimal backoff)
-      this.reconnectAttempt = 0;
-      this.scheduleReconnect();
       return;
     }
 

package/src/sleep-wake-detector.ts

@@ -0,0 +1,44 @@
+import { getLogger } from "./logger.js";
+
+const log = getLogger("sleep-wake-detector");
+
+/**
+ * Detects system sleep/wake transitions using the epoch-gap technique:
+ * a periodic timer checks if the elapsed time between ticks far exceeds
+ * the expected interval, which indicates the process was suspended.
+ */
+export class SleepWakeDetector {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastTick: number = 0;
+
+  constructor(
+    private onWake: () => void,
+    private intervalMs: number = 10_000,
+    private thresholdMultiplier: number = 2,
+  ) {}
+
+  start(): void {
+    this.stop();
+    this.lastTick = Date.now();
+    this.timer = setInterval(() => {
+      const now = Date.now();
+      const elapsed = now - this.lastTick;
+      this.lastTick = now;
+
+      if (elapsed > this.intervalMs * this.thresholdMultiplier) {
+        log.info(
+          { elapsedMs: elapsed, expectedMs: this.intervalMs },
+          "System wake detected (epoch gap)",
+        );
+        this.onWake();
+      }
+    }, this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}