mastra-ai
diff --git a/‎.changeset/tall-dots-watch.md‎
Lines changed: 41 additions & 0 deletions b/‎.changeset/tall-dots-watch.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎docs/src/content/en/models/gateways/custom-gateways.mdx‎
Lines changed: 67 additions & 17 deletions b/‎docs/src/content/en/models/gateways/custom-gateways.mdx‎
Lines changed: 67 additions & 17 deletions
diff --git a/‎docs/src/content/en/reference/core/mastra-model-gateway.mdx‎
Lines changed: 25 additions & 2 deletions b/‎docs/src/content/en/reference/core/mastra-model-gateway.mdx‎
Lines changed: 25 additions & 2 deletions
@@ -0,0 +1,41 @@
+---
+'@mastra/core': minor
+'mastracode': patch
+---
+
+Added interface-first model gateways while keeping the existing `MastraModelGateway` base class backwards compatible.
+
+Added `MastraModelGatewayInterface` for plain object/custom gateway implementations and optional gateway `resolveAuth` hooks.
+
+Moved MastraCode gateway-routed OAuth model construction into a custom Mastra gateway so `ModelRouterLanguageModel` can route through gateway `resolveAuth` and provider-specific `resolveLanguageModel` behavior.
+
+**Usage:**
+
+```typescript
+import { MastraModelGatewayInterface, ModelRouterLanguageModel } from '@mastra/core/llm';
+
+const myGateway: MastraModelGatewayInterface = {
+  id: 'my-gateway',
+  name: 'My Gateway',
+  async fetchProviders() { return {}; },
+  buildUrl() { return 'https://api.example.com'; },
+  async getApiKey() { return process.env.API_KEY ?? ''; },
+  // Optional: own authentication lookup
+  async resolveAuth(request) {
+    return { apiKey: process.env.API_KEY, source: 'gateway' };
+  },
+  async resolveLanguageModel({ modelId, providerId, apiKey }) {
+    // Return an AI SDK language model instance
+  },
+};
+
+// Register and route through the gateway
+const router = new ModelRouterLanguageModel({ modelId: 'my-gateway/provider/model' }, [myGateway]);
+```
+
+**Additional changes in this release:**
+
+- Inline three-tier auth resolution (explicit → gateway.resolveAuth → legacy getApiKey) into `ModelRouterLanguageModel.resolveAuth` and deprecate the standalone `resolveModelAuth` helper.
+- Fix `defaultGateways` deduplication in the `Mastra` class to use `getGatewayId(gateway)` instead of registry keys.
+- Remove no-op `resolveModelId` identity function in mastracode in favor of direct usage.
+- Fix `defaultNameGenerator` regex in `_llm-recorder` to anchor directory matches to path boundaries (prevents false matches like `-auth` suffixes).
@@ -5,7 +5,7 @@ description: "Create custom model gateways for private or specialized LLM deploy
 
 # Custom model gateways
 
-Custom model gateways allow you to implement private or specialized LLM provider integrations by extending the `MastraModelGateway` base class.
+Custom model gateways allow you to implement private or specialized LLM provider integrations with the `MastraModelGatewayInterface` interface or the `MastraModelGateway` base class.
 
 ## Overview
 
@@ -25,7 +25,43 @@ Create custom gateways to support:
 
 ## Creating a Custom Gateway
 
-Extend the `MastraModelGateway` class and implement the required methods:
+Implement `MastraModelGatewayInterface` for a plain object gateway, or extend `MastraModelGateway` when you want base class defaults.
+
+```typescript
+import { type MastraModelGatewayInterface, type ProviderConfig } from '@mastra/core/llm';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
+
+const myPrivateGateway: MastraModelGatewayInterface = {
+  id: 'private',
+  name: 'My Private Gateway',
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['__GATEWAY_OPENAI_MODEL__'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: 'private',
+        url: 'https://api.myprovider.com/v1',
+      },
+    };
+  },
+  buildUrl() {
+    return 'https://api.myprovider.com/v1';
+  },
+  async getApiKey() {
+    return process.env.MY_API_KEY ?? '';
+  },
+  async resolveLanguageModel({ modelId, providerId, apiKey }) {
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL: 'https://api.myprovider.com/v1',
+    }).chatModel(modelId);
+  },
+};
+```
+
+The following example extends the `MastraModelGateway` class:
 
 ```typescript
 import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
@@ -48,7 +84,7 @@ class MyPrivateGateway extends MastraModelGateway {
     return {
       'my-provider': {
         name: 'My Provider',
-        models: ['model-1', 'model-2', 'model-3'],
+        models: ['__GATEWAY_OPENAI_MODEL__', '__GATEWAY_ANTHROPIC_MODEL_SONNET__'],
         apiKeyEnvVar: 'MY_API_KEY',
         gateway: this.id,
         url: 'https://api.myprovider.com/v1',
@@ -102,6 +138,20 @@ class MyPrivateGateway extends MastraModelGateway {
 }
 ```
 
+### Gateway-owned authentication
+
+Add `resolveAuth` when the gateway owns credential lookup. Mastra uses this hook before falling back to `getApiKey()`.
+
+```typescript
+const myPrivateGateway: MastraModelGatewayInterface = {
+  // ...gateway fields and methods
+  async resolveAuth() {
+    const apiKey = process.env.MY_API_KEY;
+    return apiKey ? { apiKey, source: 'gateway' } : undefined;
+  },
+};
+```
+
 ## Registering Custom Gateways
 
 ### During Initialization
@@ -145,7 +195,7 @@ const agent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant',
-  model: 'private/my-provider/model-1', // Uses MyPrivateGateway
+  model: 'private/my-provider/__GATEWAY_OPENAI_MODEL__', // Uses MyPrivateGateway
 });
 
 mastra.addAgent(agent, 'myAgent');
@@ -155,16 +205,16 @@ When you create an agent or use a model, Mastra's model router automatically sel
 
 ### TypeScript Autocomplete
 
-**Automatic Type Generation in Development**
+#### Automatic type generation in development
 
-When running in development mode (`MASTRA_DEV=true`), Mastra automatically generates TypeScript types for your custom gateways!
+When running in development mode (`MASTRA_DEV=true`), Mastra automatically generates TypeScript types for your custom gateways.
 
 1. **Set the environment variable**:
    ```bash
    export MASTRA_DEV=true
    ```
 
-2. **Register your gateways**:
+1. **Register your gateways**:
    ```typescript
    const mastra = new Mastra({
      gateways: {
@@ -173,20 +223,20 @@ When running in development mode (`MASTRA_DEV=true`), Mastra automatically gener
    });
    ```
 
-3. **Types are generated automatically**:
+1. **Types are generated automatically**:
    - When you add a gateway, Mastra syncs with the GatewayRegistry
    - The registry fetches providers from your custom gateway
    - TypeScript types are regenerated in `~/.cache/mastra/`
    - Your IDE picks up the new types within seconds
 
-4. **Autocomplete now works**:
+1. **Autocomplete now works**:
    ```typescript
    const agent = new Agent({
      model: 'my-gateway-id/my-provider/model-1', // Full autocomplete!
    });
    ```
 
-**How It Works**
+#### How it works
 
 The GatewayRegistry runs an hourly sync that:
 - Calls `fetchProviders()` on all registered gateways
@@ -517,19 +567,19 @@ describe('MyPrivateGateway', () => {
    readonly id = 'my-gateway-v1';
    ```
 
-2. **Implement proper error handling**: Throw descriptive errors with actionable messages
+1. **Implement proper error handling**: Throw descriptive errors with actionable messages
 
-3. **Cache expensive operations**: Cache tokens, URLs, or provider configurations when appropriate
+1. **Cache expensive operations**: Cache tokens, URLs, or provider configurations when appropriate
 
-4. **Validate environment variables**: Check for required environment variables in `getApiKey` and `buildUrl`
+1. **Validate environment variables**: Check for required environment variables in `getApiKey` and `buildUrl`
 
-5. **Document your gateway**: Add JSDoc comments explaining the gateway's purpose and configuration
+1. **Document your gateway**: Add JSDoc comments explaining the gateway's purpose and configuration
 
-6. **Follow naming conventions**: Use clear, consistent naming for providers and models
+1. **Follow naming conventions**: Use clear, consistent naming for providers and models
 
-7. **Handle async operations**: Use `async/await` for network requests and I/O operations
+1. **Handle async operations**: Use `async/await` for network requests and I/O operations
 
-8. **Test thoroughly**: Write unit tests for all gateway methods
+1. **Test thoroughly**: Write unit tests for all gateway methods
 
 ## Built-in Gateways
 
 
@@ -1,6 +1,6 @@
 ---
 title: "Reference: MastraModelGateway | Core"
-description: "Base class for creating custom model gateways"
+description: "Base class and interface for creating custom model gateways"
 packages:
   - "@mastra/core"
 ---
@@ -9,6 +9,8 @@ packages:
 
 Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
 
+Use `MastraModelGatewayInterface` when you want to provide a plain object gateway instead of extending the base class.
+
 ## Class overview
 
 ```typescript
@@ -24,7 +26,7 @@ class MyCustomGateway extends MastraModelGateway {
     return {
       'my-provider': {
         name: 'My Provider',
-        models: ['model-1', 'model-2'],
+        models: ['__GATEWAY_OPENAI_MODEL__', '__GATEWAY_ANTHROPIC_MODEL_SONNET__'],
         apiKeyEnvVar: 'MY_API_KEY',
         gateway: this.id,
       },
@@ -175,6 +177,27 @@ Retrieves the API key for authentication.
 
 **Returns:** `Promise<string>`
 
+### `resolveAuth()`
+
+Resolves credentials before Mastra creates the language model. Implement this optional hook when a gateway owns authentication. If omitted, Mastra falls back to `getApiKey()`.
+
+**Parameters:**
+
+<PropertiesTable
+  content={[
+  {
+    name: 'request',
+    type: 'GatewayAuthRequest',
+    description:
+      'Incoming request context containing gatewayId, providerId, modelId, and routerId for the gateway to inspect and validate.',
+  },
+]}
+/>
+
+**Returns:** `GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>`
+
+A `GatewayAuthResult` may include `apiKey`, `bearerToken`, `headers`, and an optional `source` field to trace where auth came from.
+
 ### `resolveLanguageModel()`
 
 Creates a language model instance.