Merge branch 'main' into processors-headers

Author: mfrachet

.changeset/@mastra_google-cloud-pubsub-12265-dependencies.md

@@ -0,0 +1,5 @@
+---
+"@mastra/google-cloud-pubsub": patch
+---
+dependencies updates:
+  - Updated dependency [`@google-cloud/pubsub@^5.2.2` ↗︎](https://www.npmjs.com/package/@google-cloud/pubsub/v/5.2.2) (from `^5.2.0`, in `dependencies`)

.changeset/frank-plums-stick.md

@@ -0,0 +1,21 @@
+---
+'@mastra/core': patch
+---
+
+Fix ModelRouterLanguageModel to propagate supportedUrls from underlying model providers
+
+Previously, `ModelRouterLanguageModel` (used when specifying models as strings like `"mistral/mistral-large-latest"` or `"openai/gpt-4o"`) had `supportedUrls` hardcoded as an empty object. This caused Mastra to download all file URLs and convert them to bytes/base64, even when the model provider supports URLs natively.
+
+This fix:
+
+- Changes `supportedUrls` to a lazy `PromiseLike` that resolves the underlying model's supported URL patterns
+- Updates `llm-execution-step.ts` to properly await `supportedUrls` when preparing messages
+
+**Impact:**
+
+- Mistral: PDF URLs are now passed directly (fixes #12152)
+- OpenAI: Image URLs (and PDF URLs in response models) are now passed directly
+- Anthropic: Image URLs are now passed directly
+- Google: Files from Google endpoints are now passed directly
+
+**Note:** Users who were relying on Mastra to download files from URLs that model providers cannot directly access (internal URLs, auth-protected URLs) may need to adjust their approach by either using base64-encoded content or ensuring URLs are publicly accessible to the model provider.

.changeset/good-falcons-win.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed type error when using createTool with Agent when exactOptionalPropertyTypes is enabled in TypeScript config. The ProviderDefinedTool structural type now correctly marks inputSchema as optional and allows execute to be undefined, matching the ToolAction interface. Fixes #12281

.changeset/itchy-hornets-try.md

@@ -0,0 +1,5 @@
+---
+'@mastra/agent-builder': patch
+---
+
+Fixed latent Memory storage bug in AgentBuilder. AgentBuilder was created without providing storage to Memory, causing intermittent failures when Memory operations were invoked. Now uses InMemoryStore as a fallback when no storage is provided, allowing it to function without explicit storage configuration.

.changeset/smooth-bananas-give.md

@@ -0,0 +1,6 @@
+---
+'@mastra/playground-ui': patch
+---
+
+Remove hardcoded temperature: 0.5 and topP: 1 defaults from playground agent settings
+Let agent config and provider defaults handle these values instead

docs/src/content/en/docs/server/auth/composite-auth.mdx

@@ -0,0 +1,241 @@
+---
+title: "CompositeAuth Class | Auth"
+description: "Documentation for the CompositeAuth class, which combines multiple authentication providers into a single auth handler."
+packages:
+  - "@mastra/core"
+---
+
+# CompositeAuth Class
+
+The `CompositeAuth` class allows you to combine multiple authentication providers into a single auth handler. It tries each provider in order until one succeeds.
+
+## Use Cases
+
+- Support both API keys and OAuth tokens
+- Migrate between auth providers without breaking existing clients
+- Allow multiple identity providers (e.g., Clerk for web, API keys for integrations)
+- Gradual rollout of new authentication methods
+
+## Installation
+
+CompositeAuth is included in `@mastra/core`, no additional packages required.
+
+```typescript
+import { CompositeAuth } from '@mastra/core/server';
+```
+
+## Usage Example
+
+Combine SimpleAuth (for API keys) with Clerk (for user sessions):
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from '@mastra/core';
+import { CompositeAuth, SimpleAuth } from '@mastra/core/server';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
+
+// API key users
+type ApiKeyUser = {
+  id: string;
+  name: string;
+  type: 'api-key';
+};
+
+const apiKeyAuth = new SimpleAuth<ApiKeyUser>({
+  tokens: {
+    'sk-integration-key-123': {
+      id: 'integration-1',
+      name: 'CI/CD Pipeline',
+      type: 'api-key',
+    },
+  },
+});
+
+// Clerk users (from web app)
+const clerkAuth = new MastraAuthClerk({
+  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+  secretKey: process.env.CLERK_SECRET_KEY,
+  jwksUri: process.env.CLERK_JWKS_URI,
+});
+
+export const mastra = new Mastra({
+  server: {
+    auth: new CompositeAuth([apiKeyAuth, clerkAuth]),
+  },
+});
+```
+
+## How It Works
+
+When a request comes in, CompositeAuth:
+
+1. Extracts the token from the `Authorization` header
+2. Tries each provider's `authenticateToken()` method in order
+3. Returns the user from the first provider that succeeds
+4. Returns `null` (401 Unauthorized) if all providers fail
+
+For authorization, it calls each provider's `authorizeUser()` method until one returns `true`.
+
+```typescript
+// Pseudocode of CompositeAuth behavior
+async authenticateToken(token, request) {
+  for (const provider of this.providers) {
+    const user = await provider.authenticateToken(token, request);
+    if (user) return user;  // First match wins
+  }
+  return null;  // All providers failed
+}
+```
+
+## Provider Order
+
+The order of providers matters. Place the most common authentication method first for better performance:
+
+```typescript
+// If most requests use Clerk, put it first
+new CompositeAuth([
+  clerkAuth,      // Checked first (most common)
+  apiKeyAuth,     // Checked second (less common)
+]);
+
+// If most requests use API keys, put it first
+new CompositeAuth([
+  apiKeyAuth,     // Checked first (most common)
+  clerkAuth,      // Checked second (less common)
+]);
+```
+
+## Multiple OAuth Providers
+
+Support users from different identity providers:
+
+```typescript
+import { CompositeAuth } from '@mastra/core/server';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+const clerkAuth = new MastraAuthClerk({
+  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+  secretKey: process.env.CLERK_SECRET_KEY,
+  jwksUri: process.env.CLERK_JWKS_URI,
+});
+
+const auth0Auth = new MastraAuthAuth0({
+  domain: process.env.AUTH0_DOMAIN,
+  audience: process.env.AUTH0_AUDIENCE,
+});
+
+export const mastra = new Mastra({
+  server: {
+    auth: new CompositeAuth([clerkAuth, auth0Auth]),
+  },
+});
+```
+
+## Migration Example
+
+Migrate from JWT to Clerk while maintaining backwards compatibility:
+
+```typescript
+import { CompositeAuth } from '@mastra/core/server';
+import { MastraJwtAuth } from '@mastra/auth';
+import { MastraAuthClerk } from '@mastra/auth-clerk';
+
+// Legacy JWT auth (existing clients)
+const legacyAuth = new MastraJwtAuth({
+  secret: process.env.JWT_SECRET,
+});
+
+// New Clerk auth (new clients)
+const clerkAuth = new MastraAuthClerk({
+  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+  secretKey: process.env.CLERK_SECRET_KEY,
+  jwksUri: process.env.CLERK_JWKS_URI,
+});
+
+// Support both during migration
+export const mastra = new Mastra({
+  server: {
+    auth: new CompositeAuth([
+      clerkAuth,    // New auth method (preferred)
+      legacyAuth,   // Legacy support
+    ]),
+  },
+});
+```
+
+## With Custom Providers
+
+Combine built-in providers with custom implementations:
+
+```typescript
+import { CompositeAuth, SimpleAuth } from '@mastra/core/server';
+import { MyCustomAuth } from './my-custom-auth';
+
+const apiKeyAuth = new SimpleAuth({
+  tokens: {
+    'sk-key-123': { id: 'user-1', name: 'API User' },
+  },
+});
+
+const customAuth = new MyCustomAuth({
+  apiUrl: process.env.CUSTOM_AUTH_URL,
+});
+
+export const mastra = new Mastra({
+  server: {
+    auth: new CompositeAuth([apiKeyAuth, customAuth]),
+  },
+});
+```
+
+## Error Handling
+
+CompositeAuth silently catches errors from individual providers and moves to the next one. This prevents one failing provider from blocking authentication:
+
+```typescript
+// If clerkAuth throws an error, apiKeyAuth still gets tried
+new CompositeAuth([clerkAuth, apiKeyAuth]);
+```
+
+To debug authentication issues, add logging to your custom providers or check individual provider configurations.
+
+## Limitations
+
+- All providers share the same token from the `Authorization` header
+- User types may differ between providers (use discriminated unions if needed)
+- No built-in way to identify which provider authenticated a request
+
+### Handling Different User Types
+
+When providers return different user types, use a discriminated union:
+
+```typescript
+type ApiKeyUser = {
+  type: 'api-key';
+  id: string;
+  name: string;
+};
+
+type ClerkUser = {
+  type: 'clerk';
+  sub: string;
+  email: string;
+};
+
+type User = ApiKeyUser | ClerkUser;
+
+// In your application code
+function handleUser(user: User) {
+  if (user.type === 'api-key') {
+    console.log('API key user:', user.name);
+  } else {
+    console.log('Clerk user:', user.email);
+  }
+}
+```
+
+## Related
+
+- [Auth Overview](/docs/server/auth) - Authentication concepts
+- [Simple Auth](/docs/server/auth/simple-auth) - Token-to-user mapping
+- [Custom Auth Provider](/docs/server/auth/custom-auth-provider) - Build your own provider