@vellumai/vellum-gateway 0.4.3 → 0.4.5

package/ARCHITECTURE.md

@@ -26,6 +26,8 @@ Internet
      Gateway (http://127.0.0.1:7830)
        |
        +-- Dedicated /v1/health --> Runtime /v1/health
+       +-- /v1/integrations/twilio/* --> Runtime (Twilio control-plane proxy)
+       +-- /v1/channels/readiness* --> Runtime (channel readiness proxy)
        +-- Runtime proxy /v1/* --> Runtime (http://127.0.0.1:7821)
        +-- /webhooks/* --> BLOCKED (404, never forwarded to runtime)
 ```
@@ -154,6 +156,65 @@ Telegram integration setup/config endpoints and ingress members/invites endpoint
 | `gateway/src/http/routes/ingress-control-plane-proxy.ts` | Ingress control-plane proxy handlers and upstream forwarding |
 | `gateway/src/index.ts` | Route registration and bearer-auth enforcement for `/v1/integrations/telegram/*` and `/v1/ingress/*` |
 
+### Twilio Control-Plane Proxy
+
+Twilio integration setup/config endpoints are exposed directly by the gateway and forwarded to runtime handlers even when the broad runtime proxy is disabled. This keeps skills and clients on gateway URLs exclusively.
+
+**Forwarded endpoints:**
+
+| Method | Path |
+|--------|------|
+| GET | `/v1/integrations/twilio/config` |
+| POST | `/v1/integrations/twilio/credentials` |
+| DELETE | `/v1/integrations/twilio/credentials` |
+| GET | `/v1/integrations/twilio/numbers` |
+| POST | `/v1/integrations/twilio/numbers/provision` |
+| POST | `/v1/integrations/twilio/numbers/assign` |
+| POST | `/v1/integrations/twilio/numbers/release` |
+| GET | `/v1/integrations/twilio/sms/compliance` |
+| POST | `/v1/integrations/twilio/sms/compliance/tollfree` |
+| PATCH | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` |
+| DELETE | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` |
+| POST | `/v1/integrations/twilio/sms/test` |
+| POST | `/v1/integrations/twilio/sms/doctor` |
+
+**Authentication boundary:**
+
+- Gateway validates caller bearer auth against the runtime token.
+- Gateway forwards requests to runtime with the runtime bearer token and `X-Gateway-Origin` proof header.
+- Upstream 4xx/5xx responses are passed through, while connection errors return `502` and timeouts return `504`.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `gateway/src/http/routes/twilio-control-plane-proxy.ts` | Twilio control-plane proxy handlers and upstream forwarding |
+| `gateway/src/index.ts` | Route registration and bearer-auth enforcement for `/v1/integrations/twilio/*` |
+
+### Channel Readiness Proxy
+
+Channel readiness endpoints are exposed directly by the gateway and forwarded to runtime handlers even when the broad runtime proxy is disabled.
+
+**Forwarded endpoints:**
+
+| Method | Path |
+|--------|------|
+| GET | `/v1/channels/readiness` |
+| POST | `/v1/channels/readiness/refresh` |
+
+**Authentication boundary:**
+
+- Gateway validates caller bearer auth against the runtime token.
+- Gateway forwards requests to runtime with the runtime bearer token and `X-Gateway-Origin` proof header.
+- Upstream 4xx/5xx responses are passed through, while connection errors return `502` and timeouts return `504`.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `gateway/src/http/routes/channel-readiness-proxy.ts` | Channel readiness proxy handlers and upstream forwarding |
+| `gateway/src/index.ts` | Route registration and bearer-auth enforcement for `/v1/channels/readiness*` |
+
 ### 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 thread 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.
@@ -296,7 +357,7 @@ The guardian system adds a cryptographic trust layer for channel-based interacti
 
 #### Canonical Assistant ID Scoping
 
-All channel ingress paths canonicalize the `assistantId` via `normalizeAssistantId()` (from `util/platform.ts`) before any DB operations. The system uses `"self"` as the canonical single-tenant identifier, but callers may pass the real assistant name (e.g., `"vellum-true-eel"`) or `"self"` depending on context. `normalizeAssistantId()` maps any known lockfile assistant ID to `"self"`, ensuring consistent DB key usage regardless of how the caller identifies the assistant. This canonicalization runs at every ingress boundary: the guardian IPC handler (`config-channels.ts`), the guardian context resolver, the relay server, and the inbound message handler.
+The daemon uses the fixed constant `DAEMON_INTERNAL_ASSISTANT_ID` (`"self"`) from `runtime/assistant-scope.ts` for all assistant-scoped storage keys. Public/external assistant IDs are a gateway/platform concern and never leak into daemon scoping logic. The `normalizeAssistantId()` function in `util/platform.ts` exists solely for the gateway layer to canonicalize inbound requests before proxying -- daemon and runtime code must not call it or accept an `assistantId` parameter for scoping.
 
 #### Guardian Verify Code Parsing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",

package/src/feature-flag-registry.json

@@ -41,6 +41,14 @@
       "description": "Enable X (Twitter) skill section in the system prompt",
       "defaultEnabled": true
     },
+    {
+      "id": "messaging",
+      "scope": "assistant",
+      "key": "feature_flags.messaging.enabled",
+      "label": "Messaging",
+      "description": "Enable messaging skill section in the system prompt",
+      "defaultEnabled": true
+    },
     {
       "id": "collect-usage-data",
       "scope": "assistant",
@@ -49,14 +57,6 @@
       "description": "Send crash reports and error diagnostics to help improve the app",
       "defaultEnabled": true
     },
-    {
-      "id": "voice-invite-redemption",
-      "scope": "assistant",
-      "key": "feature_flags.voice-invite-redemption.enabled",
-      "label": "Voice Invite Redemption",
-      "description": "Enable voice invite code redemption for inbound callers with active voice invites",
-      "defaultEnabled": false
-    },
     {
       "id": "user-hosted-enabled",
       "scope": "macos",

package/src/http/routes/brain-graph-proxy.ts

@@ -0,0 +1,84 @@
+/**
+ * Gateway proxy endpoints for the brain graph knowledge-graph visualizer.
+ *
+ * Exposes GET /v1/brain-graph and GET /v1/brain-graph-ui through the gateway
+ * even when the broad runtime proxy is disabled.
+ */
+
+import type { GatewayConfig } from "../../config.js";
+import { fetchImpl } from "../../fetch.js";
+import { getLogger } from "../../logger.js";
+import { GATEWAY_ORIGIN_HEADER } from "../../runtime/client.js";
+import { stripHopByHop } from "../../util/strip-hop-by-hop.js";
+
+const log = getLogger("brain-graph-proxy");
+
+export function createBrainGraphProxyHandler(config: GatewayConfig) {
+  async function proxyTo(req: Request, upstream: string): Promise<Response> {
+    const start = performance.now();
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    reqHeaders.delete("authorization");
+
+    if (config.runtimeBearerToken) {
+      reqHeaders.set("authorization", `Bearer ${config.runtimeBearerToken}`);
+    }
+    if (config.runtimeGatewayOriginSecret) {
+      reqHeaders.set(GATEWAY_ORIGIN_HEADER, config.runtimeGatewayOriginSecret);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetchImpl(upstream, {
+        method: "GET",
+        headers: reqHeaders,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error({ duration, upstream }, "Brain graph proxy upstream timed out");
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error({ err, duration, upstream }, "Brain graph proxy upstream connection failed");
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      log.warn(
+        { status: response.status, duration, upstream },
+        "Brain graph proxy upstream error",
+      );
+      return new Response(body, { status: response.status, headers: resHeaders });
+    }
+
+    log.info({ status: response.status, duration, upstream }, "Brain graph proxy completed");
+    return new Response(response.body, { status: response.status, headers: resHeaders });
+  }
+
+  async function handleBrainGraph(req: Request): Promise<Response> {
+    return proxyTo(req, `${config.assistantRuntimeBaseUrl}/v1/brain-graph`);
+  }
+
+  async function handleBrainGraphUI(req: Request): Promise<Response> {
+    return proxyTo(req, `${config.assistantRuntimeBaseUrl}/v1/brain-graph-ui`);
+  }
+
+  async function handleHomeBaseUI(req: Request): Promise<Response> {
+    return proxyTo(req, `${config.assistantRuntimeBaseUrl}/v1/home-base-ui`);
+  }
+
+  return { handleBrainGraph, handleBrainGraphUI, handleHomeBaseUI };
+}

package/src/http/routes/channel-readiness-proxy.ts

@@ -0,0 +1,96 @@
+/**
+ * Gateway proxy endpoints for channel readiness control-plane routes.
+ *
+ * These routes remain available even when the broad runtime proxy is
+ * disabled, so skills and clients can use gateway URLs exclusively.
+ */
+
+import type { GatewayConfig } from "../../config.js";
+import { fetchImpl } from "../../fetch.js";
+import { getLogger } from "../../logger.js";
+import { GATEWAY_ORIGIN_HEADER } from "../../runtime/client.js";
+import { stripHopByHop } from "../../util/strip-hop-by-hop.js";
+
+const log = getLogger("channel-readiness-proxy");
+
+export function createChannelReadinessProxyHandler(config: GatewayConfig) {
+  async function proxyToRuntime(
+    req: Request,
+    upstreamPath: string,
+    upstreamSearch: string,
+  ): Promise<Response> {
+    const start = performance.now();
+    const upstream = `${config.assistantRuntimeBaseUrl}${upstreamPath}${upstreamSearch}`;
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    reqHeaders.delete("authorization");
+
+    if (config.runtimeBearerToken) {
+      reqHeaders.set("authorization", `Bearer ${config.runtimeBearerToken}`);
+    }
+    if (config.runtimeGatewayOriginSecret) {
+      reqHeaders.set(GATEWAY_ORIGIN_HEADER, config.runtimeGatewayOriginSecret);
+    }
+
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : null;
+    if (bodyBuffer !== null) {
+      reqHeaders.set("content-length", String(bodyBuffer.byteLength));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetchImpl(upstream, {
+        method: req.method,
+        headers: reqHeaders,
+        body: bodyBuffer,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error({ path: upstreamPath, duration }, "Channel readiness proxy upstream timed out");
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error({ err, path: upstreamPath, duration }, "Channel readiness proxy upstream connection failed");
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      log.warn(
+        { path: upstreamPath, status: response.status, duration },
+        "Channel readiness proxy upstream error",
+      );
+      return new Response(body, { status: response.status, headers: resHeaders });
+    }
+
+    log.info(
+      { path: upstreamPath, status: response.status, duration },
+      "Channel readiness proxy completed",
+    );
+    return new Response(response.body, { status: response.status, headers: resHeaders });
+  }
+
+  return {
+    async handleGetChannelReadiness(req: Request): Promise<Response> {
+      const url = new URL(req.url);
+      return proxyToRuntime(req, "/v1/channels/readiness", url.search);
+    },
+
+    async handleRefreshChannelReadiness(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/channels/readiness/refresh", "");
+    },
+  };
+}

package/src/http/routes/telegram-deliver.ts

@@ -43,7 +43,7 @@ export function createTelegramDeliverHandler(config: GatewayConfig) {
       return Response.json({ error: "Invalid JSON" }, { status: 400 });
     }
 
-    const { chatId, text, assistantId, attachments, approval, chatAction } = body;
+    const { chatId, text, assistantId: _assistantId, attachments, approval, chatAction } = body;
 
     if (!chatId || typeof chatId !== "string") {
       return Response.json({ error: "chatId is required" }, { status: 400 });

package/src/http/routes/twilio-control-plane-proxy.ts

@@ -0,0 +1,139 @@
+/**
+ * Gateway proxy endpoints for Twilio integration control-plane routes.
+ *
+ * These routes remain available even when the broad runtime proxy is
+ * disabled, so skills and clients can use gateway URLs exclusively.
+ */
+
+import type { GatewayConfig } from "../../config.js";
+import { fetchImpl } from "../../fetch.js";
+import { getLogger } from "../../logger.js";
+import { GATEWAY_ORIGIN_HEADER } from "../../runtime/client.js";
+import { stripHopByHop } from "../../util/strip-hop-by-hop.js";
+
+const log = getLogger("twilio-control-plane-proxy");
+
+export function createTwilioControlPlaneProxyHandler(config: GatewayConfig) {
+  async function proxyToRuntime(
+    req: Request,
+    upstreamPath: string,
+    upstreamSearch: string,
+  ): Promise<Response> {
+    const start = performance.now();
+    const upstream = `${config.assistantRuntimeBaseUrl}${upstreamPath}${upstreamSearch}`;
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    reqHeaders.delete("authorization");
+
+    if (config.runtimeBearerToken) {
+      reqHeaders.set("authorization", `Bearer ${config.runtimeBearerToken}`);
+    }
+    if (config.runtimeGatewayOriginSecret) {
+      reqHeaders.set(GATEWAY_ORIGIN_HEADER, config.runtimeGatewayOriginSecret);
+    }
+
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : null;
+    if (bodyBuffer !== null) {
+      reqHeaders.set("content-length", String(bodyBuffer.byteLength));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetchImpl(upstream, {
+        method: req.method,
+        headers: reqHeaders,
+        body: bodyBuffer,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error({ path: upstreamPath, duration }, "Twilio control-plane proxy upstream timed out");
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error({ err, path: upstreamPath, duration }, "Twilio control-plane proxy upstream connection failed");
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      log.warn(
+        { path: upstreamPath, status: response.status, duration },
+        "Twilio control-plane proxy upstream error",
+      );
+      return new Response(body, { status: response.status, headers: resHeaders });
+    }
+
+    log.info(
+      { path: upstreamPath, status: response.status, duration },
+      "Twilio control-plane proxy completed",
+    );
+    return new Response(response.body, { status: response.status, headers: resHeaders });
+  }
+
+  return {
+    async handleGetTwilioConfig(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/config", "");
+    },
+
+    async handleSetTwilioCredentials(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/credentials", "");
+    },
+
+    async handleClearTwilioCredentials(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/credentials", "");
+    },
+
+    async handleListTwilioNumbers(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/numbers", "");
+    },
+
+    async handleProvisionTwilioNumber(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/numbers/provision", "");
+    },
+
+    async handleAssignTwilioNumber(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/numbers/assign", "");
+    },
+
+    async handleReleaseTwilioNumber(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/numbers/release", "");
+    },
+
+    async handleGetSmsCompliance(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/sms/compliance", "");
+    },
+
+    async handleSubmitTollfreeVerification(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/sms/compliance/tollfree", "");
+    },
+
+    async handleUpdateTollfreeVerification(req: Request, verificationSid: string): Promise<Response> {
+      return proxyToRuntime(req, `/v1/integrations/twilio/sms/compliance/tollfree/${encodeURIComponent(verificationSid)}`, "");
+    },
+
+    async handleDeleteTollfreeVerification(req: Request, verificationSid: string): Promise<Response> {
+      return proxyToRuntime(req, `/v1/integrations/twilio/sms/compliance/tollfree/${encodeURIComponent(verificationSid)}`, "");
+    },
+
+    async handleSmsSendTest(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/sms/test", "");
+    },
+
+    async handleSmsDoctor(req: Request): Promise<Response> {
+      return proxyToRuntime(req, "/v1/integrations/twilio/sms/doctor", "");
+    },
+  };
+}

package/src/http/routes/whatsapp-deliver.ts

@@ -60,7 +60,7 @@ export function createWhatsAppDeliverHandler(config: GatewayConfig) {
       return Response.json({ error: "to is required" }, { status: 400 });
     }
 
-    const { text, assistantId, attachments, approval } = body;
+    const { text, assistantId: _assistantId, attachments, approval } = body;
 
     if (text !== undefined && typeof text !== "string") {
       return Response.json({ error: "text must be a string" }, { status: 400 });

package/src/index.ts

@@ -33,7 +33,10 @@ import { createGuardianControlPlaneProxyHandler } from "./http/routes/guardian-c
 import { createTelegramControlPlaneProxyHandler } from "./http/routes/telegram-control-plane-proxy.js";
 import { createIngressControlPlaneProxyHandler } from "./http/routes/ingress-control-plane-proxy.js";
 import { matchIngressControlPlaneRoute } from "./http/routes/ingress-control-plane-route-match.js";
+import { createTwilioControlPlaneProxyHandler } from "./http/routes/twilio-control-plane-proxy.js";
+import { createChannelReadinessProxyHandler } from "./http/routes/channel-readiness-proxy.js";
 import { createRuntimeHealthProxyHandler } from "./http/routes/runtime-health-proxy.js";
+import { createBrainGraphProxyHandler } from "./http/routes/brain-graph-proxy.js";
 import { validateBearerToken } from "./http/auth/bearer.js";
 import { getLogger, initLogger } from "./logger.js";
 import { CircuitBreakerOpenError } from "./runtime/client.js";
@@ -204,7 +207,10 @@ function main() {
   const guardianControlPlaneProxy = createGuardianControlPlaneProxyHandler(config);
   const telegramControlPlaneProxy = createTelegramControlPlaneProxyHandler(config);
   const ingressControlPlaneProxy = createIngressControlPlaneProxyHandler(config);
+  const twilioControlPlaneProxy = createTwilioControlPlaneProxyHandler(config);
+  const channelReadinessProxy = createChannelReadinessProxyHandler(config);
   const runtimeHealthProxy = createRuntimeHealthProxyHandler(config);
+  const brainGraphProxy = createBrainGraphProxyHandler(config);
   const handleFeatureFlagsGet = createFeatureFlagsGetHandler();
   const handleFeatureFlagsPatch = createFeatureFlagsPatchHandler();
 
@@ -447,6 +453,23 @@ function main() {
         return runtimeHealthProxy.handleRuntimeHealth(tracedReq);
       }
 
+      // ── Brain graph proxy ──
+      if (url.pathname === "/v1/brain-graph" && req.method === "GET") {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+        return brainGraphProxy.handleBrainGraph(tracedReq);
+      }
+      if (url.pathname === "/v1/brain-graph-ui" && req.method === "GET") {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+        return brainGraphProxy.handleBrainGraphUI(tracedReq);
+      }
+      if (url.pathname === "/v1/home-base-ui" && req.method === "GET") {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+        return brainGraphProxy.handleHomeBaseUI(tracedReq);
+      }
+
       // ── Telegram integration control-plane proxy ──
       if (
         (url.pathname === "/v1/integrations/telegram/config" && req.method === "GET")
@@ -525,6 +548,85 @@ function main() {
         return guardianControlPlaneProxy.handleCancelGuardianOutbound(tracedReq);
       }
 
+      // ── Twilio integration control-plane proxy ──
+      if (
+        (url.pathname === "/v1/integrations/twilio/config" && req.method === "GET")
+        || (url.pathname === "/v1/integrations/twilio/credentials" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/credentials" && req.method === "DELETE")
+        || (url.pathname === "/v1/integrations/twilio/numbers" && req.method === "GET")
+        || (url.pathname === "/v1/integrations/twilio/numbers/provision" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/numbers/assign" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/numbers/release" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/sms/compliance" && req.method === "GET")
+        || (url.pathname === "/v1/integrations/twilio/sms/compliance/tollfree" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/sms/test" && req.method === "POST")
+        || (url.pathname === "/v1/integrations/twilio/sms/doctor" && req.method === "POST")
+      ) {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+
+        if (url.pathname === "/v1/integrations/twilio/config" && req.method === "GET") {
+          return twilioControlPlaneProxy.handleGetTwilioConfig(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/credentials" && req.method === "POST") {
+          return twilioControlPlaneProxy.handleSetTwilioCredentials(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/credentials" && req.method === "DELETE") {
+          return twilioControlPlaneProxy.handleClearTwilioCredentials(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/numbers" && req.method === "GET") {
+          return twilioControlPlaneProxy.handleListTwilioNumbers(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/numbers/provision") {
+          return twilioControlPlaneProxy.handleProvisionTwilioNumber(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/numbers/assign") {
+          return twilioControlPlaneProxy.handleAssignTwilioNumber(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/numbers/release") {
+          return twilioControlPlaneProxy.handleReleaseTwilioNumber(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/sms/compliance" && req.method === "GET") {
+          return twilioControlPlaneProxy.handleGetSmsCompliance(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/sms/compliance/tollfree") {
+          return twilioControlPlaneProxy.handleSubmitTollfreeVerification(tracedReq);
+        }
+        if (url.pathname === "/v1/integrations/twilio/sms/test") {
+          return twilioControlPlaneProxy.handleSmsSendTest(tracedReq);
+        }
+        return twilioControlPlaneProxy.handleSmsDoctor(tracedReq);
+      }
+
+      // ── Twilio tollfree verification dynamic path routes ──
+      const tollfreeVerificationMatch = url.pathname.match(
+        /^\/v1\/integrations\/twilio\/sms\/compliance\/tollfree\/([^/]+)$/,
+      );
+      if (tollfreeVerificationMatch && (req.method === "PATCH" || req.method === "DELETE")) {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+
+        const verificationSid = decodeURIComponent(tollfreeVerificationMatch[1]);
+        if (req.method === "PATCH") {
+          return twilioControlPlaneProxy.handleUpdateTollfreeVerification(tracedReq, verificationSid);
+        }
+        return twilioControlPlaneProxy.handleDeleteTollfreeVerification(tracedReq, verificationSid);
+      }
+
+      // ── Channel readiness proxy ──
+      if (
+        (url.pathname === "/v1/channels/readiness" && req.method === "GET")
+        || (url.pathname === "/v1/channels/readiness/refresh" && req.method === "POST")
+      ) {
+        const authError = requireRuntimeBearerAuth();
+        if (authError) return authError;
+
+        if (url.pathname === "/v1/channels/readiness" && req.method === "GET") {
+          return channelReadinessProxy.handleGetChannelReadiness(tracedReq);
+        }
+        return channelReadinessProxy.handleRefreshChannelReadiness(tracedReq);
+      }
+
       if (url.pathname === "/integrations/status" && req.method === "GET") {
         const authError = requireRuntimeBearerAuth();
         if (authError) return authError;

package/src/schema.ts

@@ -1102,13 +1102,6 @@ export function buildSchema(): Record<string, unknown> {
               schema: { type: "string", enum: ["sms", "voice", "telegram"] },
               description: "Optional guardian channel filter.",
             },
-            {
-              name: "assistantId",
-              in: "query",
-              required: false,
-              schema: { type: "string" },
-              description: "Optional assistant identifier override.",
-            },
           ],
           responses: {
             "200": { description: "Guardian status returned" },
@@ -1196,6 +1189,339 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/integrations/twilio/config": {
+        get: {
+          summary: "Get Twilio integration config",
+          description:
+            "Authenticated gateway endpoint that returns current Twilio integration configuration from the assistant runtime.",
+          operationId: "twilioConfigGet",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": { description: "Twilio config 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/integrations/twilio/credentials": {
+        post: {
+          summary: "Set Twilio credentials",
+          description:
+            "Authenticated gateway endpoint that stores Twilio account credentials via the assistant runtime.",
+          operationId: "twilioCredentialsPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Twilio credentials stored" },
+            "400": { description: "Invalid request payload" },
+            "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" },
+          },
+        },
+        delete: {
+          summary: "Clear Twilio credentials",
+          description:
+            "Authenticated gateway endpoint that clears stored Twilio credentials via the assistant runtime.",
+          operationId: "twilioCredentialsDelete",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": { description: "Twilio credentials cleared" },
+            "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/integrations/twilio/numbers": {
+        get: {
+          summary: "List Twilio phone numbers",
+          description:
+            "Authenticated gateway endpoint that lists available Twilio phone numbers via the assistant runtime.",
+          operationId: "twilioNumbersGet",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": { description: "Twilio phone numbers 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/integrations/twilio/numbers/provision": {
+        post: {
+          summary: "Provision a Twilio phone number",
+          description:
+            "Authenticated gateway endpoint that provisions a new Twilio phone number via the assistant runtime.",
+          operationId: "twilioNumbersProvisionPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Phone number provisioned" },
+            "400": { description: "Invalid request payload" },
+            "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/integrations/twilio/numbers/assign": {
+        post: {
+          summary: "Assign a Twilio phone number",
+          description:
+            "Authenticated gateway endpoint that assigns an existing Twilio phone number to the assistant via the runtime.",
+          operationId: "twilioNumbersAssignPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Phone number assigned" },
+            "400": { description: "Invalid request payload" },
+            "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/integrations/twilio/numbers/release": {
+        post: {
+          summary: "Release a Twilio phone number",
+          description:
+            "Authenticated gateway endpoint that releases an assigned Twilio phone number via the assistant runtime.",
+          operationId: "twilioNumbersReleasePost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Phone number released" },
+            "400": { description: "Invalid request payload" },
+            "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/integrations/twilio/sms/compliance": {
+        get: {
+          summary: "Get SMS compliance status",
+          description:
+            "Authenticated gateway endpoint that returns SMS compliance/registration status from the assistant runtime.",
+          operationId: "twilioSmsComplianceGet",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": { description: "SMS compliance 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/integrations/twilio/sms/compliance/tollfree": {
+        post: {
+          summary: "Submit toll-free verification",
+          description:
+            "Authenticated gateway endpoint that submits a toll-free number verification request via the assistant runtime.",
+          operationId: "twilioSmsTollfreePost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Toll-free verification submitted" },
+            "400": { description: "Invalid request payload" },
+            "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/integrations/twilio/sms/compliance/tollfree/{verificationSid}": {
+        patch: {
+          summary: "Update toll-free verification",
+          description:
+            "Authenticated gateway endpoint that updates an existing toll-free verification via the assistant runtime.",
+          operationId: "twilioSmsTollfreePatch",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "verificationSid",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Toll-free verification updated" },
+            "400": { description: "Invalid request payload" },
+            "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" },
+          },
+        },
+        delete: {
+          summary: "Delete toll-free verification",
+          description:
+            "Authenticated gateway endpoint that deletes a toll-free verification via the assistant runtime.",
+          operationId: "twilioSmsTollfreeDelete",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "verificationSid",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          responses: {
+            "200": { description: "Toll-free verification deleted" },
+            "401": { description: "Unauthorized — missing or invalid bearer token" },
+            "404": { description: "Verification not found" },
+            "503": { description: "Bearer token not configured" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/integrations/twilio/sms/test": {
+        post: {
+          summary: "Send a test SMS",
+          description:
+            "Authenticated gateway endpoint that sends a test SMS message via the assistant runtime.",
+          operationId: "twilioSmsTestPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Test SMS sent" },
+            "400": { description: "Invalid request payload" },
+            "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/integrations/twilio/sms/doctor": {
+        post: {
+          summary: "Run SMS doctor diagnostics",
+          description:
+            "Authenticated gateway endpoint that runs SMS integration diagnostics via the assistant runtime.",
+          operationId: "twilioSmsDoctorPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "SMS doctor diagnostics returned" },
+            "400": { description: "Invalid request payload" },
+            "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": {
+        get: {
+          summary: "Get channel readiness",
+          description:
+            "Authenticated gateway endpoint that returns the readiness status of all configured channels from the assistant runtime.",
+          operationId: "channelReadinessGet",
+          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",
+          description:
+            "Authenticated gateway endpoint that triggers a fresh readiness check for all channels via the assistant runtime.",
+          operationId: "channelReadinessRefreshPost",
+          security: [{ BearerAuth: [] }],
+          requestBody: {
+            required: false,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": { description: "Channel readiness refreshed" },
+            "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" },
+          },
+        },
+      },
       "/integrations/status": {
         get: {
           summary: "Integration status",