feat(void): support custom Workers AI bindings

Author: TheAlexLichter

docs/integrations/cloudflare.md

@@ -98,12 +98,12 @@ Bindings are [inferred automatically](../reference/resource-inference.md) by sca
 ```json
 {
   "inference": {
-    "bindings": { "db": true, "kv": true, "storage": false, "ai": true }
+    "bindings": { "db": true, "kv": true, "storage": false, "ai": "MY_AI" }
   }
 }
 ```
 
-`db`, `kv`, and `storage` accept a string to customize the binding name (e.g. `"db": "MY_DB"`). `ai` only accepts a boolean.
+Every binding accepts a string to customize its name (for example, `"db": "MY_DB"` or `"ai": "MY_AI"`).
 
 See [Configuration](../reference/config.md) for details.
 
@@ -349,7 +349,7 @@ That's it. The Cloudflare Vite plugin produces a complete build output with a me
 
 `void/ai` works on your own Cloudflare account, along two paths:
 
-- **Workers AI** (`ai.run`, `ai.stream`, `ai.image`) works out of the box. When your app imports `void/ai`, `vite build` infers that you need AI and adds a Workers AI binding (`env.AI`) to the generated `wrangler.json` automatically -- you do **not** add it to `wrangler.jsonc`.
+- **Workers AI** (`ai.run`, `ai.stream`, `ai.image`) works out of the box. When your app imports `void/ai`, `vite build` infers that you need AI and adds a Workers AI binding (`env.AI`) to the generated `wrangler.json` automatically -- you do **not** add it to `wrangler.jsonc`. Set `inference.bindings.ai` to a string to use a custom name.
 - **Provider models** (`ai.provider("openai").fetch(...)`) route through _your own_ Cloudflare AI Gateway. Set its id in `void.json` and add the provider's API key as a Worker secret.
 
 ```jsonc
@@ -372,7 +372,7 @@ import { defineHandler } from 'void';
 import { ai } from 'void/ai';
 
 export const POST = defineHandler(async (c) => {
-  // Workers AI -- uses env.AI directly
+  // Workers AI -- uses the inferred or configured AI binding directly
   const summary = await ai.run('@cf/meta/llama-3.1-8b-instruct', {
     prompt: 'Summarize the changelog.',
   });
@@ -393,7 +393,7 @@ export const POST = defineHandler(async (c) => {
 Notes:
 
 - **No cross-tenant usage metering.** On the Void platform, AI calls are metered and billed through a shared proxy. Self-hosted, there is no metering -- you get your own [Cloudflare AI Gateway analytics](https://developers.cloudflare.com/ai-gateway/) instead.
-- **The runtime reads the `env.AI` binding by name** -- a custom-named root AI binding is not supported.
+- **Custom AI binding names are supported.** Configure `"inference": { "bindings": { "ai": "MY_AI" } }`, or declare the custom `ai.binding` in your root Wrangler config; the generated worker records the resolved name for `void/ai` automatically.
 - **`void dev` has no local Workers AI emulation.** In development, AI still routes through Void, so `void dev` AI requires `void auth login` even when you deploy self-hosted.
 
 ### ISR (self-host)

docs/reference/config.md

@@ -422,17 +422,17 @@ Explicitly control inferred Cloudflare bindings. If omitted, bindings are [autom
 Each binding accepts `true` (use default name), `false` (disable), or a string (custom binding name):
 
 ```json
-{ "inference": { "bindings": { "db": true, "kv": false, "storage": "MY_BUCKET" } } }
+{ "inference": { "bindings": { "db": true, "kv": false, "storage": "MY_BUCKET", "ai": "MY_AI" } } }
 ```
 
 | Key       | Default Binding | Type          | Custom Name              |
 | --------- | --------------- | ------------- | ------------------------ |
 | `db`      | `DB`            | `D1Database`  | `"db": "MY_DB"`          |
 | `kv`      | `KV`            | `KVNamespace` | `"kv": "MY_KV"`          |
 | `storage` | `STORAGE`       | `R2Bucket`    | `"storage": "MY_BUCKET"` |
-| `ai`      | `AI`            | `Ai`          | Boolean only             |
+| `ai`      | `AI`            | `Ai`          | `"ai": "MY_AI"`          |
 
-Custom names are used in the deploy manifest, Wrangler config generation/sync, remote binding proxying, internal migrations, and generated runtime helpers such as `void/db`, `void/kv`, and `void/storage`.
+Custom names are used in generated Wrangler config and runtime helpers such as `void/db`, `void/kv`, `void/storage`, and `void/ai`. Resource binding names also flow through deploy manifests, remote binding proxying, and internal migrations where applicable. Managed Workers AI continues to use Void's service proxy.
 
 #### `inference.build`
 

packages/void/CLAUDE.md

@@ -93,8 +93,8 @@ src/
 
 Two features need extra wiring on a self-hosted `vite build && wrangler deploy` (no Void platform proxy/dispatch in front of the worker). Both are inert on managed `void deploy`.
 
-- **`ai.gateway` config + `__VOID_AI_GATEWAY` var** — `void.json`'s `ai.gateway` (validated in `config.ts` as `ai?: { gateway?: string }`; non-empty string, `additionalProperties: false`) names a Cloudflare AI Gateway in the user's own account. `mergeBindings` (`index.ts`): (1) injects `{ ai: { binding: 'AI' } }`, but only when `shouldBindWorkersAi()` is true — the app infers `needsAI`, `command === 'build'`, and neither the resolved root wrangler config nor the result already declares an `ai` binding (so it never clobbers a user's own `ai` binding); (2) emits `vars.__VOID_AI_GATEWAY = config.ai.gateway` whenever `config.ai?.gateway` is set. At runtime, `runtime/ai.ts` `resolveBackend()` selects the direct backend (Priority 3) when `env.AI` is present and no `__VOID_PROXY`/`__VOID_TOKEN` exists. `ai.run/stream/image` hit Workers AI directly; `ai.provider().fetch()` routes through the user's own gateway via `directAi.gateway(__VOID_AI_GATEWAY).getUrl(provider)` with the provider key from the user's own secret (`resolveProviderKey` → `env[PROVIDER_KEY_MAP[provider]]`), returning HTTP 501 if `__VOID_AI_GATEWAY` is unset. No cross-tenant metering on this path. The runtime reads `env.AI` **by name** — a custom-named root AI binding is not honored.
-- **Internal-binding leak check permits exactly `__VOID_AI_GATEWAY`** — the integration guard (`test/integration/kitchen-sink-build.test.ts`) that asserts no `__VOID_*` var reaches `dist/ssr/wrangler.json` explicitly excludes `__VOID_AI_GATEWAY`, because it is a legitimate, non-credential runtime var (unlike the credential keys in `INTERNAL_ENV_KEYS`, which are stripped).
+- **`ai.gateway`, custom AI bindings, and private runtime vars** — `void.json`'s `ai.gateway` (validated in `config.ts` as `ai?: { gateway?: string }`; non-empty string, `additionalProperties: false`) names a Cloudflare AI Gateway in the user's own account. `inference.bindings.ai` accepts a string custom binding name. `mergeBindings` (`index.ts`) injects the resolved binding only when `shouldBindWorkersAi()` is true — the app infers `needsAI`, `command === 'build'`, and neither the resolved root wrangler config nor the result already declares an `ai` binding — so a root Wrangler declaration stays authoritative. It emits `vars.__VOID_AI_BINDING` for a non-default binding and `vars.__VOID_AI_GATEWAY` when configured. At runtime, `runtime/ai.ts` `resolveBackend()` uses that resolved binding when no `__VOID_PROXY`/`__VOID_TOKEN` exists. `ai.run/stream/image` hit Workers AI directly; `ai.provider().fetch()` routes through the user's own gateway via `directAi.gateway(__VOID_AI_GATEWAY).getUrl(provider)` with the provider key from the user's own secret (`resolveProviderKey` → `env[PROVIDER_KEY_MAP[provider]]`), returning HTTP 501 if `__VOID_AI_GATEWAY` is unset. No cross-tenant metering on this path.
+- **Internal-binding leak check permits the AI routing markers** — the integration guard (`test/integration/kitchen-sink-build.test.ts`) that asserts no credential-bearing `__VOID_*` var reaches `dist/ssr/wrangler.json` permits `__VOID_AI_BINDING` and `__VOID_AI_GATEWAY`, because they are legitimate, non-credential runtime routing values (unlike the credential keys in `INTERNAL_ENV_KEYS`, which are stripped).
 - **`ISR_CACHE` self-host requirement** — self-host ISR (`runtime/isr-cache.ts`, `runtime/isr.ts`) reads `env.ISR_CACHE` (a `KVNamespace`) + `env.__VOID_ISR_DEPLOYMENT_ID`. Unlike D1/KV/R2, `ISR_CACHE` is **not** auto-injected (a KV binding needs a real namespace id), so the user must create the namespace and declare it as `ISR_CACHE` in their root wrangler config. `routing.revalidate` (void.json) and per-page `export const revalidate` are merged by `collectRevalidate` (`isr-config.ts`) and baked as `__VOID_ISR_REVALIDATE`. On-demand `revalidate()` on self-host purges the worker's own KV (global) plus the local-colo `caches.default` edge variants only.
 
 ### Package Exports

packages/void/schema.json

@@ -257,8 +257,8 @@
               "description": "Enable R2 bucket binding. `true` uses default name \"STORAGE\", a string sets a custom binding name."
             },
             "ai": {
-              "type": "boolean",
-              "description": "Enable Workers AI binding"
+              "oneOf": [{ "type": "boolean" }, { "type": "string" }],
+              "description": "Enable Workers AI binding. `true` uses default name \"AI\", a string sets a custom binding name."
             }
           },
           "additionalProperties": false

packages/void/src/cli/deploy.ts

@@ -883,8 +883,8 @@ const DEPLOY_RAW_SNAPSHOT_FIELDS: ReadonlyArray<string> = [
   'migrations',
 ];
 
-/** Void's own injected Workers AI binding shape (`mergeBindings` in index.ts). */
-const VOID_EMITTED_AI_BINDING = { binding: 'AI' };
+/** Void's default injected Workers AI binding name (`mergeBindings` in index.ts). */
+const DEFAULT_VOID_AI_BINDING = 'AI';
 
 /**
  * Sub-fields on a `durable_objects` binding that make it target ANOTHER worker's Durable Objects.
@@ -1565,12 +1565,14 @@ export function verifyGeneratedDeployConfig(
     passthroughRawFields?: Map<string, unknown>;
     /**
      * Whether the pre-build inference found Workers AI use in the source (the SAME `needsAI`
-     * signal `shouldBindWorkersAi` gates on in index.ts). Authorizes an emitted `{binding:'AI'}`
-     * ai binding when the root config declares no ai binding: only an AI-using app legitimately
-     * receives Void's injected Workers AI binding, so a build that injects one into a non-AI app
-     * (billable inference the source never asked for) fails closed.
+     * signal `shouldBindWorkersAi` gates on in index.ts). Authorizes Void's emitted AI binding
+     * (default `AI`, or `aiBindingName`) when the root config declares none: only an AI-using app
+     * legitimately receives one, so a build that injects it into a non-AI app (billable inference
+     * the source never asked for) fails closed.
      */
     needsAI?: boolean;
+    /** Custom `inference.bindings.ai` name authorized for Void's emitted AI binding. */
+    aiBindingName?: string;
     /**
      * The exact `containers` set Void's build emits, reconstructed PRE-BUILD
      * ({@link reconstructExpectedContainers}) from the root-declared containers plus — when the
@@ -1812,8 +1814,8 @@ export function verifyGeneratedDeployConfig(
   //   • `ai` — when the root declared its own ai binding it must SURVIVE byte-identical (a build
   //     that REMOVED or rewrote it is rejected); otherwise the emitted binding must be ABSENT or —
   //     ONLY when the source's pre-build inference says the app uses Workers AI — Void's own
-  //     `{binding:'AI'}`. An injected `{binding:'AI'}` on an app that does not use AI would incur
-  //     account-billed inference from build-injected worker code.
+  //     its configured Workers AI binding. An injected AI binding on an app that does not use AI
+  //     would incur account-billed inference from build-injected worker code.
   //   • `migrations` — an emitted Durable Object migration carrying a DESTRUCTIVE key (deleting,
   //     renaming, or transferring classes) must match a root-declared migration byte-for-byte;
   //     Void emits only creation-key migrations, so a destructive one is a build injection that
@@ -1857,10 +1859,10 @@ export function verifyGeneratedDeployConfig(
         };
       }
     } else if (emittedAi !== undefined) {
-      // No root ai binding: the only ai binding Void's own build emits is `{binding:'AI'}`, and
-      // ONLY when the pre-build inference says the source uses Workers AI (the SAME signal
-      // `shouldBindWorkersAi` gates on). Anything else here is a build-injected billable binding.
-      if (!(expected.needsAI === true && deepEqual(emittedAi, VOID_EMITTED_AI_BINDING))) {
+      // No root ai binding: Void emits the configured binding name (default `AI`) ONLY when
+      // pre-build inference says the source uses Workers AI. Anything else is build-injected.
+      const expectedAi = { binding: expected.aiBindingName ?? DEFAULT_VOID_AI_BINDING };
+      if (!(expected.needsAI === true && deepEqual(emittedAi, expectedAi))) {
         return {
           ok: false,
           reason: `generated config declares an ai binding the build injected — the pre-build inference found no Workers AI use in the source and the root config declares no ai binding.`,
@@ -2481,10 +2483,12 @@ export async function computeDesiredCloudflareResources(
   migrations: Array<{ name: string; sql: string }>;
   /**
    * Whether the pre-build inference found Workers AI use in the source — the SAME `needsAI`
-   * signal `shouldBindWorkersAi` (index.ts) gates the emitted `{binding:'AI'}` on. Threaded
-   * into {@link verifyGeneratedDeployConfig} to authorize that emitted ai binding.
+   * signal `shouldBindWorkersAi` (index.ts) gates the emitted AI binding on. Threaded into
+   * {@link verifyGeneratedDeployConfig} to authorize that binding.
    */
   needsAI: boolean;
+  /** Workers AI binding emitted by the build (default `AI`). */
+  aiBindingName: string;
   /**
    * Whether Void's build emits the sandbox container application — the SAME signal `mergeBindings`
    * (index.ts) gates emission on: `isSandboxEnabled(config)` (a `sandbox` field in `void.json`) OR
@@ -2642,6 +2646,7 @@ export async function computeDesiredCloudflareResources(
     migrationsDir: paths.migrationsDir,
     migrations,
     needsAI: bindings.needsAI,
+    aiBindingName: bindingNames?.ai ?? DEFAULT_VOID_AI_BINDING,
     expectedCrons,
     // Mirror index.ts's emission signal EXACTLY (line 658): the sandbox container is emitted when
     // `void.json` enables it OR the source imports `void/sandbox` (the import-walk signal). Using
@@ -3625,6 +3630,7 @@ export async function runCloudflareDeploy(
     migrationsDir,
     migrations: preBuildMigrations,
     needsAI,
+    aiBindingName,
     needsSandbox,
     expectedCrons,
   } = await computeDesiredCloudflareResources(root, voidConfig, configPath);
@@ -4550,6 +4556,7 @@ export async function runCloudflareDeploy(
     passthroughIdentitySnapshot,
     passthroughRawFields,
     needsAI,
+    aiBindingName,
     expectedContainers,
     expectedCrons,
   });

packages/void/src/config.ts

@@ -63,7 +63,7 @@ export type InferenceConfig = {
     db?: boolean | string;
     kv?: boolean | string;
     storage?: boolean | string;
-    ai?: boolean;
+    ai?: boolean | string;
   };
   scanDirs?: ReadonlyArray<string>;
   build?: string;
@@ -762,18 +762,10 @@ export function readConfig(root: string): VoidConfig {
             `config: Unknown binding '${key}' in ${CONFIG_FILE}. Valid: db, kv, storage, ai.`,
           );
         }
-        if (key === 'ai') {
-          if (typeof b[key] !== 'boolean') {
-            throw new Error(
-              `config: "inference.bindings.${key}" in ${CONFIG_FILE} must be a boolean.`,
-            );
-          }
-        } else {
-          if (typeof b[key] !== 'boolean' && typeof b[key] !== 'string') {
-            throw new Error(
-              `config: "inference.bindings.${key}" in ${CONFIG_FILE} must be a boolean or a string custom binding name.`,
-            );
-          }
+        if (typeof b[key] !== 'boolean' && typeof b[key] !== 'string') {
+          throw new Error(
+            `config: "inference.bindings.${key}" in ${CONFIG_FILE} must be a boolean or a string custom binding name.`,
+          );
         }
       }
     }
@@ -988,11 +980,11 @@ export function isNodeTarget(target: VoidConfig['target']): boolean {
  */
 export function resolveBindingNames(
   bindings: InferenceConfig['bindings'],
-): { d1?: string; kv?: string; r2?: string } | undefined {
+): { d1?: string; kv?: string; r2?: string; ai?: string } | undefined {
   if (!bindings) {
     return undefined;
   }
-  const names: { d1?: string; kv?: string; r2?: string } = {};
+  const names: { d1?: string; kv?: string; r2?: string; ai?: string } = {};
   let hasCustom = false;
   if (typeof bindings.db === 'string') {
     names.d1 = bindings.db;
@@ -1006,6 +998,10 @@ export function resolveBindingNames(
     names.r2 = bindings.storage;
     hasCustom = true;
   }
+  if (typeof bindings.ai === 'string') {
+    names.ai = bindings.ai;
+    hasCustom = true;
+  }
   return hasCustom ? names : undefined;
 }
 

packages/void/src/index.ts

@@ -384,6 +384,17 @@ export function shouldBindWorkersAi(
   return needsAI && command === 'build' && !resultAi && !resolvedAi;
 }
 
+/** Resolve the runtime Workers AI binding, preserving a root Wrangler declaration. */
+export function resolveWorkersAiBindingName(resolvedAi: unknown, configuredName?: string): string {
+  if (typeof resolvedAi === 'object' && resolvedAi !== null) {
+    const binding = (resolvedAi as { binding?: unknown }).binding;
+    if (typeof binding === 'string') {
+      return binding;
+    }
+  }
+  return configuredName ?? 'AI';
+}
+
 const CLOUDFLARE_BUILTIN_IMPORT = /^cloudflare:/;
 const SANDBOX_SDK_IMPORT = '@cloudflare/sandbox';
 const SANDBOX_SDK_IMPORT_FILTER = /^@cloudflare\/sandbox$/;
@@ -1051,22 +1062,29 @@ export function voidPlugin(options?: {
     // wins, so `!resolvedAi` is load-bearing (prevents clobbering a user's own
     // root-wrangler `ai` binding); `!resultAi` is harmless defense-in-depth
     // (nothing else in mergeBindings ever sets `result.ai`).
+    const resolvedAi = (resolved as { ai?: unknown }).ai;
+    const aiBindingName = resolveWorkersAiBindingName(resolvedAi, bindingNames?.ai);
     if (
       shouldBindWorkersAi(
         viteCommand,
         bindings.needsAI,
-        (resolved as { ai?: unknown }).ai,
+        resolvedAi,
         (result as { ai?: unknown }).ai,
       )
     ) {
-      (result as Record<string, unknown>).ai = { binding: 'AI' };
+      (result as Record<string, unknown>).ai = { binding: aiBindingName };
     }
 
-    // AI Gateway id → runtime var (harmless in serve; only read by the P3 direct
-    // backend that routes Workers AI inference through the user's own Gateway).
-    if (config.ai?.gateway) {
+    // AI binding name / Gateway id → runtime vars (harmless in serve; only read
+    // by the P3 direct backend). The default binding needs no extra variable.
+    if (aiBindingName !== 'AI' || config.ai?.gateway) {
       const vars = (result.vars as Record<string, string>) ?? {};
-      vars.__VOID_AI_GATEWAY = config.ai.gateway;
+      if (aiBindingName !== 'AI') {
+        vars.__VOID_AI_BINDING = aiBindingName;
+      }
+      if (config.ai?.gateway) {
+        vars.__VOID_AI_GATEWAY = config.ai.gateway;
+      }
       result.vars = vars;
     }
 

packages/void/src/plugin-inference.ts

@@ -88,7 +88,7 @@ export type InferenceOptions = {
     db?: boolean | string;
     kv?: boolean | string;
     storage?: boolean | string;
-    ai?: boolean;
+    ai?: boolean | string;
   };
   paths?: ProjectPaths;
 };

packages/void/src/runtime/ai.ts

@@ -407,8 +407,12 @@ function resolveBackend(): AiBackend {
     return makeHttpBackend(token, projectId, runtimeEnv);
   }
 
-  // Priority 3: Direct AI binding (user's own CF account)
-  const directAi = runtimeEnv.AI as Ai | undefined;
+  // Priority 3: Direct AI binding (user's own CF account). Void's generated
+  // wrangler config stamps custom binding names into a private runtime var;
+  // default and managed deployments continue to use `AI`.
+  const aiBindingName =
+    typeof runtimeEnv.__VOID_AI_BINDING === 'string' ? runtimeEnv.__VOID_AI_BINDING : 'AI';
+  const directAi = runtimeEnv[aiBindingName] as Ai | undefined;
   if (directAi) {
     return makeDirectBackend(
       directAi,
@@ -418,7 +422,7 @@ function resolveBackend(): AiBackend {
   }
 
   throw new Error(
-    'ai: Not available. Run `void auth login` and `void project link` first, or bind Workers AI (env.AI) for self-hosted deploys.',
+    `ai: Not available. Run \`void auth login\` and \`void project link\` first, or bind Workers AI (env.${aiBindingName}) for self-hosted deploys.`,
   );
 }