@mastra/mcp-docs-server 0.13.44 → 0.13.45

package/.docs/organized/changelogs/%40mastra%2Fcore.md

@@ -1,302 +1,502 @@
 # @mastra/core
 
-## 0.24.5
+## 0.24.6
 
 ### Patch Changes
 
-- Fix parallel tool call handling for Gemini models ([#10371](https://github.com/mastra-ai/mastra/pull/10371))
-  - Fix addStartStepPartsForAIV5 to prevent step-start parts from being inserted between consecutive tool parts (parallel tool calls)
-  - This ensures parallel tool calls maintain correct order and preserve thought_signature metadata on the first tool call as required by Gemini API
+- Fix base64 encoded images with threads - issue #10480 ([#10566](https://github.com/mastra-ai/mastra/pull/10566))
 
-## 0.24.5-alpha.0
+  Fixed "Invalid URL" error when using base64 encoded images (without `data:` prefix) in agent calls with threads and resources. Raw base64 strings are now automatically converted to proper data URIs before being processed.
 
-### Patch Changes
-
-- Fix parallel tool call handling for Gemini models ([#10371](https://github.com/mastra-ai/mastra/pull/10371))
-  - Fix addStartStepPartsForAIV5 to prevent step-start parts from being inserted between consecutive tool parts (parallel tool calls)
-  - This ensures parallel tool calls maintain correct order and preserve thought_signature metadata on the first tool call as required by Gemini API
-
-## 0.24.4
-
-### Patch Changes
-
-- Fix providerMetadata preservation for Gemini function calls ([#10365](https://github.com/mastra-ai/mastra/pull/10365))
-  - Convert stream chunks directly to MastraMessageV2 format in loop steps to preserve providerMetadata
-  - Add message-level providerMetadata support to MastraMessageContentV2 and V3 types
-  - Fix sanitizeV5UIMessages filtering to match original 0.x behavior
-  - Hydrate threadId and resourceId from memoryInfo when missing
-  - Update test utilities for 0.x compatibility
-
-## 0.24.4-alpha.0
-
-### Patch Changes
-
-- Fix providerMetadata preservation for Gemini function calls ([#10365](https://github.com/mastra-ai/mastra/pull/10365))
-  - Convert stream chunks directly to MastraMessageV2 format in loop steps to preserve providerMetadata
-  - Add message-level providerMetadata support to MastraMessageContentV2 and V3 types
-  - Fix sanitizeV5UIMessages filtering to match original 0.x behavior
-  - Hydrate threadId and resourceId from memoryInfo when missing
-  - Update test utilities for 0.x compatibility
-
-## 0.24.3
-
-### Patch Changes
-
-- Allow provider to pass through options to the auth config ([#10290](https://github.com/mastra-ai/mastra/pull/10290))
-
-- Fix deprecation warning when agent network executes workflows by using `.fullStream` instead of iterating `WorkflowRunOutput` directly ([#10306](https://github.com/mastra-ai/mastra/pull/10306))
-
-- Fix generate toolResults and mismatch in provider tool names ([#10297](https://github.com/mastra-ai/mastra/pull/10297))
-
-## 0.24.3-alpha.0
-
-### Patch Changes
-
-- Allow provider to pass through options to the auth config ([#10290](https://github.com/mastra-ai/mastra/pull/10290))
-
-- Fix deprecation warning when agent network executes workflows by using `.fullStream` instead of iterating `WorkflowRunOutput` directly ([#10306](https://github.com/mastra-ai/mastra/pull/10306))
-
-- Fix generate toolResults and mismatch in provider tool names ([#10297](https://github.com/mastra-ai/mastra/pull/10297))
-
-## 0.24.2
-
-### Patch Changes
-
-- Only handle download image asset transformation if needed ([#10245](https://github.com/mastra-ai/mastra/pull/10245))
-
-- Fix tool outputSchema validation to allow unsupported Zod types like ZodTuple. The outputSchema is only used for internal validation and never sent to the LLM, so model compatibility checks are not needed. ([#10123](https://github.com/mastra-ai/mastra/pull/10123))
-
-- Fix vector definition to fix pinecone ([#10179](https://github.com/mastra-ai/mastra/pull/10179))
+  **Changes:**
+  - Updated `attachments-to-parts.ts` to detect and convert raw base64 strings to data URIs
+  - Fixed `MessageList` image processing to handle raw base64 in two locations:
+    - Image part conversion in `aiV4CoreMessageToV1PromptMessage`
+    - File part to experimental_attachments conversion in `mastraDBMessageToAIV4UIMessage`
+  - Added comprehensive tests for base64 images, data URIs, and HTTP URLs with threads
+
+  **Breaking Change:** None - this is a bug fix that maintains backward compatibility while adding support for raw base64 strings.
+
+- SimpleAuth and improved CloudAuth ([#10569](https://github.com/mastra-ai/mastra/pull/10569))
+
+- Fixed OpenAI schema compatibility when using `agent.generate()` or `agent.stream()` with `structuredOutput`. ([#10454](https://github.com/mastra-ai/mastra/pull/10454))
+
+  ## Changes
+  - **Automatic transformation**: Zod schemas are now automatically transformed for OpenAI strict mode compatibility when using OpenAI models (including reasoning models like o1, o3, o4)
+  - **Optional field handling**: `.optional()` fields are converted to `.nullable()` with a transform that converts `null` → `undefined`, preserving optional semantics while satisfying OpenAI's strict mode requirements
+  - **Preserves nullable fields**: Intentionally `.nullable()` fields remain unchanged
+  - **Deep transformation**: Handles `.optional()` fields at any nesting level (objects, arrays, unions, etc.)
+  - **JSON Schema objects**: Not transformed, only Zod schemas
+
+  ## Example
+
+  ```typescript
+  const agent = new Agent({
+    name: 'data-extractor',
+    model: { provider: 'openai', modelId: 'gpt-4o' },
+    instructions: 'Extract user information',
+  });
+
+  const schema = z.object({
+    name: z.string(),
+    age: z.number().optional(),
+    deletedAt: z.date().nullable(),
+  });
+
+  // Schema is automatically transformed for OpenAI compatibility
+  const result = await agent.generate('Extract: John, deleted yesterday', {
+    structuredOutput: { schema },
+  });
+
+  // Result: { name: 'John', age: undefined, deletedAt: null }
+  ```
 
-- Add type bailed to workflowRunStatus ([#10103](https://github.com/mastra-ai/mastra/pull/10103))
+- deleteVectors, deleteFilter when upserting, updateVector filter (#10244) ([#10526](https://github.com/mastra-ai/mastra/pull/10526))
+
+- Fix generateTitle model type to accept AI SDK LanguageModelV2 ([#10567](https://github.com/mastra-ai/mastra/pull/10567))
+
+  Updated the `generateTitle.model` config option to accept `MastraModelConfig` instead of `MastraLanguageModel`. This allows users to pass raw AI SDK `LanguageModelV2` models (e.g., `anthropic.languageModel('claude-3-5-haiku-20241022')`) directly without type errors.
+
+  Previously, passing a standard `LanguageModelV2` would fail because `MastraLanguageModelV2` has different `doGenerate`/`doStream` return types. Now `MastraModelConfig` is used consistently across:
+  - `memory/types.ts` - `generateTitle.model` config
+  - `agent.ts` - `genTitle`, `generateTitleFromUserMessage`, `resolveTitleGenerationConfig`
+  - `agent-legacy.ts` - `AgentLegacyCapabilities` interface
+
+- Fix message metadata not persisting when using simple message format. Previously, custom metadata passed in messages (e.g., `{role: 'user', content: 'text', metadata: {userId: '123'}}`) was not being saved to the database. This occurred because the CoreMessage conversion path didn't preserve metadata fields. ([#10571](https://github.com/mastra-ai/mastra/pull/10571))
+
+  Now metadata is properly preserved for all message input formats:
+  - Simple CoreMessage format: `{role, content, metadata}`
+  - Full UIMessage format: `{role, content, parts, metadata}`
+  - AI SDK v5 ModelMessage format with metadata
+
+  Fixes #8556
+
+- feat: Composite auth implementation ([#10486](https://github.com/mastra-ai/mastra/pull/10486))
+
+- Fix requireApproval property being ignored for tools passed via toolsets, clientTools, and memoryTools parameters. The requireApproval flag now correctly propagates through all tool conversion paths, ensuring tools requiring approval will properly request user approval before execution. ([#10562](https://github.com/mastra-ai/mastra/pull/10562))
+
+- Fix Azure Foundry rate limit handling for -1 values ([#10411](https://github.com/mastra-ai/mastra/pull/10411))
+
+- Fix model headers not being passed through gateway system ([#10564](https://github.com/mastra-ai/mastra/pull/10564))
+
+  Previously, custom headers specified in `MastraModelConfig` were not being passed through the gateway system to model providers. This affected:
+  - OpenRouter (preventing activity tracking with `HTTP-Referer` and `X-Title`)
+  - Custom providers using custom URLs (headers not passed to `createOpenAICompatible`)
+  - Custom gateway implementations (headers not available in `resolveLanguageModel`)
+
+  Now headers are correctly passed through the entire gateway system:
+  - Base `MastraModelGateway` interface updated to accept headers
+  - `ModelRouterLanguageModel` passes headers from config to all gateways
+  - OpenRouter receives headers for activity tracking
+  - Custom URL providers receive headers via `createOpenAICompatible`
+  - Custom gateways can access headers in their `resolveLanguageModel` implementation
+
+  Example usage:
+
+  ```typescript
+  // Works with OpenRouter
+  const agent = new Agent({
+    name: 'my-agent',
+    instructions: 'You are a helpful assistant.',
+    model: {
+      id: 'openrouter/anthropic/claude-3-5-sonnet',
+      headers: {
+        'HTTP-Referer': 'https://myapp.com',
+        'X-Title': 'My Application',
+      },
+    },
+  });
+
+  // Also works with custom providers
+  const customAgent = new Agent({
+    name: 'custom-agent',
+    instructions: 'You are a helpful assistant.',
+    model: {
+      id: 'custom-provider/model',
+      url: 'https://api.custom.com/v1',
+      apiKey: 'key',
+      headers: {
+        'X-Custom-Header': 'custom-value',
+      },
+    },
+  });
+  ```
 
-- Add support for doGenerate in LanguageModelV2. This change fixes issues with OpenAI stream permissions. ([#10268](https://github.com/mastra-ai/mastra/pull/10268))
-  - Added new abstraction over LanguageModelV2
+  Fixes https://github.com/mastra-ai/mastra/issues/9760
 
-## 0.24.2-alpha.0
+- fix(agent): persist messages before tool suspension ([#10542](https://github.com/mastra-ai/mastra/pull/10542))
 
-### Patch Changes
+  Fixes issues where thread and messages were not saved before suspension when tools require approval or call suspend() during execution. This caused conversation history to be lost if users refreshed during tool approval or suspension.
 
-- Only handle download image asset transformation if needed ([#10245](https://github.com/mastra-ai/mastra/pull/10245))
+  **Backend changes (@mastra/core):**
+  - Add assistant messages to messageList immediately after LLM execution
+  - Flush messages synchronously before suspension to persist state
+  - Create thread if it doesn't exist before flushing
+  - Add metadata helpers to persist and remove tool approval state
+  - Pass saveQueueManager and memory context through workflow for immediate persistence
 
-- Fix tool outputSchema validation to allow unsupported Zod types like ZodTuple. The outputSchema is only used for internal validation and never sent to the LLM, so model compatibility checks are not needed. ([#10123](https://github.com/mastra-ai/mastra/pull/10123))
+  **Frontend changes (@mastra/react):**
+  - Extract runId from pending approvals to enable resumption after refresh
+  - Convert `pendingToolApprovals` (DB format) to `requireApprovalMetadata` (runtime format)
+  - Handle both `dynamic-tool` and `tool-{NAME}` part types for approval state
+  - Change runId from hardcoded `agentId` to unique `uuid()`
 
-- Fix vector definition to fix pinecone ([#10179](https://github.com/mastra-ai/mastra/pull/10179))
+  **UI changes (@mastra/playground-ui):**
+  - Handle tool calls awaiting approval in message initialization
+  - Convert approval metadata format when loading initial messages
 
-- Add type bailed to workflowRunStatus ([#10103](https://github.com/mastra-ai/mastra/pull/10103))
+  Fixes #9745, #9906
 
-- Add support for doGenerate in LanguageModelV2. This change fixes issues with OpenAI stream permissions. ([#10268](https://github.com/mastra-ai/mastra/pull/10268))
-  - Added new abstraction over LanguageModelV2
+- Fix race condition in parallel tool stream writes ([#10481](https://github.com/mastra-ai/mastra/pull/10481))
 
-## 0.24.1
+  Introduces a write queue to ToolStream to serialize access to the underlying stream, preventing writer locked errors
 
-### Patch Changes
+- Remove unneeded console warning when flushing messages and no threadId or saveQueueManager is found. ([#10542](https://github.com/mastra-ai/mastra/pull/10542))
 
-- Integrates the native **Mistral AI SDK** provider (`@ai-sdk/mistral`) to replace the current OpenAI-compatible endpoint implementation for Mistral models. ([#10048](https://github.com/mastra-ai/mastra/pull/10048))
+- Fixes GPT-5 reasoning which was failing on subsequent tool calls with the error: ([#10489](https://github.com/mastra-ai/mastra/pull/10489))
 
-- Fix: Don't download unsupported media ([#9860](https://github.com/mastra-ai/mastra/pull/9860))
+  ```
+  Item 'fc_xxx' of type 'function_call' was provided without its required 'reasoning' item: 'rs_xxx'
+  ```
 
-- Use a shared `getAllToolPaths()` method from the bundler to discover tool paths. ([#10049](https://github.com/mastra-ai/mastra/pull/10049))
+- Add optional includeRawChunks parameter to agent execution options, ([#10459](https://github.com/mastra-ai/mastra/pull/10459))
+  allowing users to include raw chunks in stream output where supported
+  by the model provider.
 
-- Add an additional check to determine whether the model natively supports specific file types. Only download the file if the model does not support it natively. ([#10052](https://github.com/mastra-ai/mastra/pull/10052))
+- When `mastra dev` runs, multiple processes can write to `provider-registry.json` concurrently (auto-refresh, syncGateways, syncGlobalCacheToLocal). This causes file corruption where the end of the JSON appears twice, making it unparseable. ([#10529](https://github.com/mastra-ai/mastra/pull/10529))
 
-- Fix agent network iteration counter bug causing infinite loops ([#9934](https://github.com/mastra-ai/mastra/pull/9934))
+  The fix uses atomic writes via the write-to-temp-then-rename pattern. Instead of:
 
-  The iteration counter in agent networks was stuck at 0 due to a faulty ternary operator that treated 0 as falsy. This prevented `maxSteps` from working correctly, causing infinite loops when the routing agent kept selecting primitives instead of returning "none".
+  ```ts
+  fs.writeFileSync(filePath, content, 'utf-8');
+  ```
 
-  **Changes:**
-  - Fixed iteration counter logic in `loop/network/index.ts` from `(inputData.iteration ? inputData.iteration : -1) + 1` to `(inputData.iteration ?? -1) + 1`
-  - Changed initial iteration value from `0` to `-1` so first iteration correctly starts at 0
-  - Added `checkIterations()` helper to validate iteration counting in all network tests
+  We now do:
 
-  Fixes #9314
+  ```ts
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${randomSuffix}.tmp`;
+  fs.writeFileSync(tempPath, content, 'utf-8');
+  fs.renameSync(tempPath, filePath); // atomic on POSIX
+  ```
 
-- Revert download supported files for now ([`16a324f`](https://github.com/mastra-ai/mastra/commit/16a324f8c30a07d0d899bc2e4e7998c6b40a4cb6))
+  `fs.rename()` is atomic on POSIX systems when both paths are on the same filesystem, so concurrent writes will each complete fully rather than interleaving.
+
+- Ensures that data chunks written via `writer.custom()` always bubble up directly to the top-level stream, even when nested in sub-agents. This allows tools to emit custom progress updates, metrics, and other data that can be consumed at any level of the agent hierarchy. ([#10523](https://github.com/mastra-ai/mastra/pull/10523))
+  - **Added bubbling logic in sub-agent execution**: When sub-agents execute, data chunks (chunks with type starting with `data-`) are detected and written via `writer.custom()` instead of `writer.write()`, ensuring they bubble up directly without being wrapped in `tool-output` chunks.
+  - **Added comprehensive tests**:
+    - Test for `writer.custom()` with direct tool execution
+    - Test for `writer.custom()` with sub-agent tools (nested execution)
+    - Test for mixed usage of `writer.write()` and `writer.custom()` in the same tool
+
+  When a sub-agent's tool uses `writer.custom()` to write data chunks, those chunks appear in the sub-agent's stream. The parent agent's execution logic now detects these chunks and uses `writer.custom()` to bubble them up directly, preserving their structure and making them accessible at the top level.
+
+  This ensures that:
+  - Data chunks from tools always appear directly in the stream (not wrapped)
+  - Data chunks bubble up correctly through nested agent hierarchies
+  - Regular chunks continue to be wrapped in `tool-output` as expected
+
+- Adds ability to create custom `MastraModelGateway`'s that can be added to the `Mastra` class instance under the `gateways` property. Giving you typescript autocompletion in any model picker string. ([#10535](https://github.com/mastra-ai/mastra/pull/10535))
+
+  ```typescript
+  import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
+  import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+  import type { LanguageModelV2 } from '@ai-sdk/provider';
+
+  class MyCustomGateway extends MastraModelGateway {
+    readonly id = 'custom';
+    readonly name = 'My Custom Gateway';
+
+    async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+      return {
+        'my-provider': {
+          name: 'My Provider',
+          models: ['model-1', 'model-2'],
+          apiKeyEnvVar: 'MY_API_KEY',
+          gateway: this.id,
+        },
+      };
+    }
+
+    buildUrl(modelId: string, envVars?: Record<string, string>): string {
+      return 'https://api.my-provider.com/v1';
+    }
+
+    async getApiKey(modelId: string): Promise<string> {
+      const apiKey = process.env.MY_API_KEY;
+      if (!apiKey) throw new Error('MY_API_KEY not set');
+      return apiKey;
+    }
+
+    async resolveLanguageModel({
+      modelId,
+      providerId,
+      apiKey,
+    }: {
+      modelId: string;
+      providerId: string;
+      apiKey: string;
+    }): Promise<LanguageModelV2> {
+      const baseURL = this.buildUrl(`${providerId}/${modelId}`);
+      return createOpenAICompatible({
+        name: providerId,
+        apiKey,
+        baseURL,
+      }).chatModel(modelId);
+    }
+  }
+
+  new Mastra({
+    gateways: {
+      myGateway: new MyCustomGateway(),
+    },
+  });
+  ```
 
-- Exposes requiresAuth to custom api routes ([#10046](https://github.com/mastra-ai/mastra/pull/10046))
+- Support AI SDK voice models ([#10558](https://github.com/mastra-ai/mastra/pull/10558))
 
-- Fix agent network working memory tool routing. Memory tools are now included in routing agent instructions but excluded from its direct tool calls, allowing the routing agent to properly route to tool execution steps for memory updates. ([#9730](https://github.com/mastra-ai/mastra/pull/9730))
+  Mastra now supports AI SDK's transcription and speech models directly in `CompositeVoice`, enabling seamless integration with a wide range of voice providers through the AI SDK ecosystem. This allows you to use models from OpenAI, ElevenLabs, Groq, Deepgram, LMNT, Hume, and many more for both speech-to-text (transcription) and text-to-speech capabilities.
 
-- Fixes assets not being downloaded when available ([#10080](https://github.com/mastra-ai/mastra/pull/10080))
+  AI SDK models are automatically wrapped when passed to `CompositeVoice`, so you can mix and match AI SDK models with existing Mastra voice providers for maximum flexibility.
 
-## 0.24.1-alpha.0
+  ## Usage Example
 
-### Patch Changes
+  ```typescript
+  import { CompositeVoice } from '@mastra/core/voice';
+  import { openai } from '@ai-sdk/openai';
+  import { elevenlabs } from '@ai-sdk/elevenlabs';
 
-- Integrates the native **Mistral AI SDK** provider (`@ai-sdk/mistral`) to replace the current OpenAI-compatible endpoint implementation for Mistral models. ([#10048](https://github.com/mastra-ai/mastra/pull/10048))
+  // Use AI SDK models directly with CompositeVoice
+  const voice = new CompositeVoice({
+    input: openai.transcription('whisper-1'), // AI SDK transcription model
+    output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech model
+  });
 
-- Fix: Don't download unsupported media ([#9860](https://github.com/mastra-ai/mastra/pull/9860))
+  // Convert text to speech
+  const audioStream = await voice.speak('Hello from AI SDK!');
 
-- Use a shared `getAllToolPaths()` method from the bundler to discover tool paths. ([#10049](https://github.com/mastra-ai/mastra/pull/10049))
+  // Convert speech to text
+  const transcript = await voice.listen(audioStream);
+  console.log(transcript);
+  ```
 
-- Add an additional check to determine whether the model natively supports specific file types. Only download the file if the model does not support it natively. ([#10052](https://github.com/mastra-ai/mastra/pull/10052))
+  Fixes #9947
 
-- Fix agent network iteration counter bug causing infinite loops ([#9934](https://github.com/mastra-ai/mastra/pull/9934))
+- Fix network data step formatting in AI SDK stream transformation ([#10525](https://github.com/mastra-ai/mastra/pull/10525))
 
-  The iteration counter in agent networks was stuck at 0 due to a faulty ternary operator that treated 0 as falsy. This prevented `maxSteps` from working correctly, causing infinite loops when the routing agent kept selecting primitives instead of returning "none".
+  Previously, network execution steps were not being tracked correctly in the AI SDK stream transformation. Steps were being duplicated rather than updated, and critical metadata like step IDs, iterations, and task information was missing or incorrectly structured.
 
   **Changes:**
-  - Fixed iteration counter logic in `loop/network/index.ts` from `(inputData.iteration ? inputData.iteration : -1) + 1` to `(inputData.iteration ?? -1) + 1`
-  - Changed initial iteration value from `0` to `-1` so first iteration correctly starts at 0
-  - Added `checkIterations()` helper to validate iteration counting in all network tests
-
-  Fixes #9314
-
-- Revert download supported files for now ([`16a324f`](https://github.com/mastra-ai/mastra/commit/16a324f8c30a07d0d899bc2e4e7998c6b40a4cb6))
+  - Enhanced step tracking in `AgentNetworkToAISDKTransformer` to properly maintain step state throughout execution lifecycle
+  - Steps are now identified by unique IDs and updated in place rather than creating duplicates
+  - Added proper iteration and task metadata to each step in the network execution flow
+  - Fixed agent, workflow, and tool execution events to correctly populate step data
+  - Updated network stream event types to include `networkId`, `workflowId`, and consistent `runId` tracking
+  - Added test coverage for network custom data chunks with comprehensive validation
 
-- Exposes requiresAuth to custom api routes ([#10046](https://github.com/mastra-ai/mastra/pull/10046))
+  This ensures the AI SDK correctly represents the full execution flow of agent networks with accurate step sequencing and metadata.
 
-- Fix agent network working memory tool routing. Memory tools are now included in routing agent instructions but excluded from its direct tool calls, allowing the routing agent to properly route to tool execution steps for memory updates. ([#9730](https://github.com/mastra-ai/mastra/pull/9730))
+- Fix generating provider-registry.json ([#10535](https://github.com/mastra-ai/mastra/pull/10535))
 
-- Fixes assets not being downloaded when available ([#10080](https://github.com/mastra-ai/mastra/pull/10080))
+- Fix message-list conversion issues when persisting messages before tool suspension: filter internal metadata fields (`__originalContent`) from UI messages, keep reasoning field empty for consistent cache keys during message deduplication, and only include providerMetadata on parts when defined. ([#10552](https://github.com/mastra-ai/mastra/pull/10552))
 
-## 0.24.0
+- Fix agent.generate() to use model's doGenerate method instead of doStream ([#10572](https://github.com/mastra-ai/mastra/pull/10572))
 
-### Patch Changes
-
-- update peerdeps ([`5ca1cca`](https://github.com/mastra-ai/mastra/commit/5ca1ccac61ffa7141e6d9fa8f22d3ad4d03bf5dc))
-
-- Fix workflow input property preservation after resume from snapshot ([#9527](https://github.com/mastra-ai/mastra/pull/9527))
-
-  Ensure that when resuming a workflow from a snapshot, the input property is correctly set from the snapshot's context input rather than from resume data. This prevents the loss of original workflow input data during suspend/resume cycles.
-
-- Fix a bug where streaming didn't output the final chunk ([#9726](https://github.com/mastra-ai/mastra/pull/9726))
-
-- Fixes issue where clicking the reset button in the model picker would fail to restore the original LanguageModelV2 (or any other types) object that was passed during agent construction. ([#9487](https://github.com/mastra-ai/mastra/pull/9487))
-
-- Fix network routing agent smoothstreaming ([#9727](https://github.com/mastra-ai/mastra/pull/9727))
-
-- Updated dependencies [[`5ca1cca`](https://github.com/mastra-ai/mastra/commit/5ca1ccac61ffa7141e6d9fa8f22d3ad4d03bf5dc)]:
-  - @mastra/schema-compat@0.11.7
-
-## 0.24.0-alpha.0
-
-### Patch Changes
+  When calling `agent.generate()`, the model's `doGenerate` method is now correctly invoked instead of always using `doStream`. This aligns the non-streaming generation path with the intended behavior where providers can implement optimized non-streaming responses.
 
-- update peerdeps ([`5ca1cca`](https://github.com/mastra-ai/mastra/commit/5ca1ccac61ffa7141e6d9fa8f22d3ad4d03bf5dc))
+- Updated dependencies [[`33a607a`](https://github.com/mastra-ai/mastra/commit/33a607a1f716c2029d4a1ff1603dd756129a33b3)]:
+  - @mastra/schema-compat@0.11.8
 
-- Fix workflow input property preservation after resume from snapshot ([#9527](https://github.com/mastra-ai/mastra/pull/9527))
-
-  Ensure that when resuming a workflow from a snapshot, the input property is correctly set from the snapshot's context input rather than from resume data. This prevents the loss of original workflow input data during suspend/resume cycles.
-
-- Fix a bug where streaming didn't output the final chunk ([#9726](https://github.com/mastra-ai/mastra/pull/9726))
-
-- Fixes issue where clicking the reset button in the model picker would fail to restore the original LanguageModelV2 (or any other types) object that was passed during agent construction. ([#9487](https://github.com/mastra-ai/mastra/pull/9487))
-
-- Fix network routing agent smoothstreaming ([#9727](https://github.com/mastra-ai/mastra/pull/9727))
-
-- Updated dependencies [[`5ca1cca`](https://github.com/mastra-ai/mastra/commit/5ca1ccac61ffa7141e6d9fa8f22d3ad4d03bf5dc)]:
-  - @mastra/schema-compat@0.11.7-alpha.0
-
-## 0.23.3
+## 0.24.6-alpha.0
 
 ### Patch Changes
 
-- Allow resuming nested workflow step with chained id ([#9464](https://github.com/mastra-ai/mastra/pull/9464))
+- Fix base64 encoded images with threads - issue #10480 ([#10566](https://github.com/mastra-ai/mastra/pull/10566))
 
-  Example, you have a workflow like this
+  Fixed "Invalid URL" error when using base64 encoded images (without `data:` prefix) in agent calls with threads and resources. Raw base64 strings are now automatically converted to proper data URIs before being processed.
 
+  **Changes:**
+  - Updated `attachments-to-parts.ts` to detect and convert raw base64 strings to data URIs
+  - Fixed `MessageList` image processing to handle raw base64 in two locations:
+    - Image part conversion in `aiV4CoreMessageToV1PromptMessage`
+    - File part to experimental_attachments conversion in `mastraDBMessageToAIV4UIMessage`
+  - Added comprehensive tests for base64 images, data URIs, and HTTP URLs with threads
+
+  **Breaking Change:** None - this is a bug fix that maintains backward compatibility while adding support for raw base64 strings.
+
+- SimpleAuth and improved CloudAuth ([#10569](https://github.com/mastra-ai/mastra/pull/10569))
+
+- Fixed OpenAI schema compatibility when using `agent.generate()` or `agent.stream()` with `structuredOutput`. ([#10454](https://github.com/mastra-ai/mastra/pull/10454))
+
+  ## Changes
+  - **Automatic transformation**: Zod schemas are now automatically transformed for OpenAI strict mode compatibility when using OpenAI models (including reasoning models like o1, o3, o4)
+  - **Optional field handling**: `.optional()` fields are converted to `.nullable()` with a transform that converts `null` → `undefined`, preserving optional semantics while satisfying OpenAI's strict mode requirements
+  - **Preserves nullable fields**: Intentionally `.nullable()` fields remain unchanged
+  - **Deep transformation**: Handles `.optional()` fields at any nesting level (objects, arrays, unions, etc.)
+  - **JSON Schema objects**: Not transformed, only Zod schemas
+
+  ## Example
+
+  ```typescript
+  const agent = new Agent({
+    name: 'data-extractor',
+    model: { provider: 'openai', modelId: 'gpt-4o' },
+    instructions: 'Extract user information',
+  });
+
+  const schema = z.object({
+    name: z.string(),
+    age: z.number().optional(),
+    deletedAt: z.date().nullable(),
+  });
+
+  // Schema is automatically transformed for OpenAI compatibility
+  const result = await agent.generate('Extract: John, deleted yesterday', {
+    structuredOutput: { schema },
+  });
+
+  // Result: { name: 'John', age: undefined, deletedAt: null }
   ```
-  export const supportWorkflow = mainWorkflow.then(nestedWorkflow).commit();
-  ```
-
-  And a step in `nestedWorkflow` is supsended, you can now also resume it any of these ways:
 
-  ```
-  run.resume({
-    step: "nestedWorkflow.suspendedStep", //chained nested workflow step id and suspended step id
-    //other resume params
-   })
+- deleteVectors, deleteFilter when upserting, updateVector filter (#10244) ([#10526](https://github.com/mastra-ai/mastra/pull/10526))
+
+- Fix generateTitle model type to accept AI SDK LanguageModelV2 ([#10567](https://github.com/mastra-ai/mastra/pull/10567))
+
+  Updated the `generateTitle.model` config option to accept `MastraModelConfig` instead of `MastraLanguageModel`. This allows users to pass raw AI SDK `LanguageModelV2` models (e.g., `anthropic.languageModel('claude-3-5-haiku-20241022')`) directly without type errors.
+
+  Previously, passing a standard `LanguageModelV2` would fail because `MastraLanguageModelV2` has different `doGenerate`/`doStream` return types. Now `MastraModelConfig` is used consistently across:
+  - `memory/types.ts` - `generateTitle.model` config
+  - `agent.ts` - `genTitle`, `generateTitleFromUserMessage`, `resolveTitleGenerationConfig`
+  - `agent-legacy.ts` - `AgentLegacyCapabilities` interface
+
+- Fix message metadata not persisting when using simple message format. Previously, custom metadata passed in messages (e.g., `{role: 'user', content: 'text', metadata: {userId: '123'}}`) was not being saved to the database. This occurred because the CoreMessage conversion path didn't preserve metadata fields. ([#10571](https://github.com/mastra-ai/mastra/pull/10571))
+
+  Now metadata is properly preserved for all message input formats:
+  - Simple CoreMessage format: `{role, content, metadata}`
+  - Full UIMessage format: `{role, content, parts, metadata}`
+  - AI SDK v5 ModelMessage format with metadata
+
+  Fixes #8556
+
+- feat: Composite auth implementation ([#10486](https://github.com/mastra-ai/mastra/pull/10486))
+
+- Fix requireApproval property being ignored for tools passed via toolsets, clientTools, and memoryTools parameters. The requireApproval flag now correctly propagates through all tool conversion paths, ensuring tools requiring approval will properly request user approval before execution. ([#10562](https://github.com/mastra-ai/mastra/pull/10562))
+
+- Fix Azure Foundry rate limit handling for -1 values ([#10411](https://github.com/mastra-ai/mastra/pull/10411))
+
+- Fix model headers not being passed through gateway system ([#10564](https://github.com/mastra-ai/mastra/pull/10564))
+
+  Previously, custom headers specified in `MastraModelConfig` were not being passed through the gateway system to model providers. This affected:
+  - OpenRouter (preventing activity tracking with `HTTP-Referer` and `X-Title`)
+  - Custom providers using custom URLs (headers not passed to `createOpenAICompatible`)
+  - Custom gateway implementations (headers not available in `resolveLanguageModel`)
+
+  Now headers are correctly passed through the entire gateway system:
+  - Base `MastraModelGateway` interface updated to accept headers
+  - `ModelRouterLanguageModel` passes headers from config to all gateways
+  - OpenRouter receives headers for activity tracking
+  - Custom URL providers receive headers via `createOpenAICompatible`
+  - Custom gateways can access headers in their `resolveLanguageModel` implementation
+
+  Example usage:
+
+  ```typescript
+  // Works with OpenRouter
+  const agent = new Agent({
+    name: 'my-agent',
+    instructions: 'You are a helpful assistant.',
+    model: {
+      id: 'openrouter/anthropic/claude-3-5-sonnet',
+      headers: {
+        'HTTP-Referer': 'https://myapp.com',
+        'X-Title': 'My Application',
+      },
+    },
+  });
+
+  // Also works with custom providers
+  const customAgent = new Agent({
+    name: 'custom-agent',
+    instructions: 'You are a helpful assistant.',
+    model: {
+      id: 'custom-provider/model',
+      url: 'https://api.custom.com/v1',
+      apiKey: 'key',
+      headers: {
+        'X-Custom-Header': 'custom-value',
+      },
+    },
+  });
   ```
 
-  OR
+  Fixes https://github.com/mastra-ai/mastra/issues/9760
 
-  ```
-  run.resume({
-    step: "nestedWorkflow", // just the nested workflow step/step id
-    //other resume params
-   })
-  ```
+- fix(agent): persist messages before tool suspension ([#10542](https://github.com/mastra-ai/mastra/pull/10542))
 
-- Fix creating system messages from inside processors using processInput. ([#9476](https://github.com/mastra-ai/mastra/pull/9476))
+  Fixes issues where thread and messages were not saved before suspension when tools require approval or call suspend() during execution. This caused conversation history to be lost if users refreshed during tool approval or suspension.
 
-- Prevent changing workflow status to suspended when some parallel steps are still running ([#9460](https://github.com/mastra-ai/mastra/pull/9460))
+  **Backend changes (@mastra/core):**
+  - Add assistant messages to messageList immediately after LLM execution
+  - Flush messages synchronously before suspension to persist state
+  - Create thread if it doesn't exist before flushing
+  - Add metadata helpers to persist and remove tool approval state
+  - Pass saveQueueManager and memory context through workflow for immediate persistence
 
-## 0.23.3-alpha.0
+  **Frontend changes (@mastra/react):**
+  - Extract runId from pending approvals to enable resumption after refresh
+  - Convert `pendingToolApprovals` (DB format) to `requireApprovalMetadata` (runtime format)
+  - Handle both `dynamic-tool` and `tool-{NAME}` part types for approval state
+  - Change runId from hardcoded `agentId` to unique `uuid()`
 
-### Patch Changes
+  **UI changes (@mastra/playground-ui):**
+  - Handle tool calls awaiting approval in message initialization
+  - Convert approval metadata format when loading initial messages
 
-- Allow resuming nested workflow step with chained id ([#9464](https://github.com/mastra-ai/mastra/pull/9464))
+  Fixes #9745, #9906
 
-  Example, you have a workflow like this
+- Fix race condition in parallel tool stream writes ([#10481](https://github.com/mastra-ai/mastra/pull/10481))
 
-  ```
-  export const supportWorkflow = mainWorkflow.then(nestedWorkflow).commit();
-  ```
+  Introduces a write queue to ToolStream to serialize access to the underlying stream, preventing writer locked errors
 
-  And a step in `nestedWorkflow` is supsended, you can now also resume it any of these ways:
+- Remove unneeded console warning when flushing messages and no threadId or saveQueueManager is found. ([#10542](https://github.com/mastra-ai/mastra/pull/10542))
 
-  ```
-  run.resume({
-    step: "nestedWorkflow.suspendedStep", //chained nested workflow step id and suspended step id
-    //other resume params
-   })
-  ```
-
-  OR
+- Fixes GPT-5 reasoning which was failing on subsequent tool calls with the error: ([#10489](https://github.com/mastra-ai/mastra/pull/10489))
 
   ```
-  run.resume({
-    step: "nestedWorkflow", // just the nested workflow step/step id
-    //other resume params
-   })
+  Item 'fc_xxx' of type 'function_call' was provided without its required 'reasoning' item: 'rs_xxx'
   ```
 
-- Fix creating system messages from inside processors using processInput. ([#9476](https://github.com/mastra-ai/mastra/pull/9476))
-
-- Prevent changing workflow status to suspended when some parallel steps are still running ([#9460](https://github.com/mastra-ai/mastra/pull/9460))
-
-## 0.23.2
-
-### Patch Changes
+- Add optional includeRawChunks parameter to agent execution options, ([#10459](https://github.com/mastra-ai/mastra/pull/10459))
+  allowing users to include raw chunks in stream output where supported
+  by the model provider.
 
-- Fix agent onChunk callback receiving wrapped chunk instead of direct chunk ([#9402](https://github.com/mastra-ai/mastra/pull/9402))
+- When `mastra dev` runs, multiple processes can write to `provider-registry.json` concurrently (auto-refresh, syncGateways, syncGlobalCacheToLocal). This causes file corruption where the end of the JSON appears twice, making it unparseable. ([#10529](https://github.com/mastra-ai/mastra/pull/10529))
 
-- Ensure model_generation spans end before agent_run spans. ([#9393](https://github.com/mastra-ai/mastra/pull/9393))
+  The fix uses atomic writes via the write-to-temp-then-rename pattern. Instead of:
 
-- Fix OpenAI schema validation errors in processors ([#9400](https://github.com/mastra-ai/mastra/pull/9400))
-
-- Don't call `os.homedir()` at top level (but lazy invoke it) to accommodate sandboxed environments ([#9357](https://github.com/mastra-ai/mastra/pull/9357))
-
-- Detect thenable objects returned by AI model providers ([#9414](https://github.com/mastra-ai/mastra/pull/9414))
-
-- Bug fix: Use input processors that are passed in generate or stream agent options rather than always defaulting to the processors set on the Agent class. ([#9422](https://github.com/mastra-ai/mastra/pull/9422))
-
-- Fix tool input validation to use schema-compat transformed schemas ([#9360](https://github.com/mastra-ai/mastra/pull/9360))
-
-  Previously, tool input validation used the original Zod schema while the LLM received a schema-compat transformed version. This caused validation failures when LLMs (like OpenAI o3 or Claude 3.5 Haiku) sent arguments matching the transformed schema but not the original.
-
-  For example:
-  - OpenAI o3 reasoning models convert `.optional()` to `.nullable()`, sending `null` values
-  - Claude 3.5 Haiku strips `min`/`max` string constraints, sending shorter strings
-  - Validation would reject these valid responses because it checked against the original schema
-
-  The fix ensures validation uses the same schema-compat processed schema that was sent to the LLM, eliminating this mismatch.
-
-- Add import for WritableStream in execution-engine and dedupe llm.getModel in agent.ts ([#9341](https://github.com/mastra-ai/mastra/pull/9341))
+  ```ts
+  fs.writeFileSync(filePath, content, 'utf-8');
+  ```
 
-- pass writableStream parameter to workflow execution ([#9339](https://github.com/mastra-ai/mastra/pull/9339))
+  We now do:
 
-- Save correct status in snapshot for all workflow parallel steps. ([#9398](https://github.com/mastra-ai/mastra/pull/9398))
-  This ensures when you poll workflow run result using `getWorkflowRunExecutionResult(runId)`, you get the right status for all parallel steps
+  ```ts
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${randomSuffix}.tmp`;
+  fs.writeFileSync(tempPath, content, 'utf-8');
+  fs.renameSync(tempPath, filePath); // atomic on POSIX
+  ```
 
-- Add ability to pass agent options when wrapping an agent with createStep. This allows configuring agent execution settings when using agents as workflow steps. ([#9359](https://github.com/mastra-ai/mastra/pull/9359))
+  `fs.rename()` is atomic on POSIX systems when both paths are on the same filesystem, so concurrent writes will each complete fully rather than interleaving.
 
-- Fix network loop iteration counter and usage promise handling: ([#9415](https://github.com/mastra-ai/mastra/pull/9415))
-  - Fixed iteration counter in network loop that was stuck at 0 due to falsy check. Properly handled zero values to ensure maxSteps is correctly enforced.
-  - Fixed usage promise resolution in RunOutput stream by properly resolving or rejecting the promise on stream close, preventing hanging promises when streams complete.
+- Ensures that data chunks written via `writer.custom()` always bubble up directly to the top-level stream, even when nested in sub-agents. This allows tools to emit custom progress updates, metrics, and other data that can be consumed at any level of the agent hierarchy. ([#10523](https://github.com/mastra-ai/mastra/pull/10523))
+  - **Added bubbling logic in sub-agent execution**: When sub-agents execute, data chunks (chunks with type starting with `data-`) are detected and written via `writer.custom()` instead of `writer.write()`, ensuring they bubble up directly without being wrapped in `tool-output` chunks.
+  - **Added comprehensive tests**:
+    - Test for `writer.custom()` with direct tool execution
+    - Test for `writer.custom()` with sub-agent tools (nested execution)
+    - Test for mixed usage of `writer.write()` and `writer.custom()` in the same tool
 
-- Workflow validation zod v4 support ([#9363](https://github.com/mastra-ai/mastra/pull/9363))
+  When a sub-agent's tool uses `writer.custom()` to write data chunks, those chunks appear in the sub-agent's stream. The parent agent's execution logic now detects these chunks and uses `writer.custom()` to bubble them up directly, preserving their structure and making them accessible at the top level.
 
+  This ensures that:
+  - Data chunks from tools always appear directly in the stream (not wrapped)
 
-... 4933 more lines hidden. See full changelog in package directory.
+... 5345 more lines hidden. See full changelog in package directory.