@mastra/mcp-docs-server 1.1.41 → 1.1.42-alpha.11

package/.docs/guides/guide/slack-assistant.md

@@ -48,7 +48,7 @@ export const slackAgent = new Agent({
   name: 'Slack Agent',
   instructions:
     'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
-  model: 'anthropic/claude-opus-4-6',
+  model: 'anthropic/claude-opus-4-7',
   channels: {
     adapters: {
       slack: createSlackAdapter(),

package/.docs/guides/guide/stock-agent.md

@@ -24,7 +24,7 @@ To create an agent in Mastra use the `Agent` class to define it and then registe
      name: 'Stock Agent',
      instructions:
        'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.',
-     model: 'openai/gpt-5.4',
+     model: 'openai/gpt-5.5',
    })
    ```
 
@@ -83,7 +83,7 @@ The Stock Agent doesn't yet know anything about current stock prices. To change
      name: 'Stock Agent',
      instructions:
        'You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.',
-     model: 'openai/gpt-5.4',
+     model: 'openai/gpt-5.5',
      tools: {
        stockPrices,
      },

package/.docs/guides/guide/whatsapp-chat-bot.md

@@ -117,7 +117,7 @@ export const chatAgent = new Agent({
 
     Always aim to be helpful while maintaining a friendly, approachable conversation style.
   `,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'agent-storage',
@@ -155,7 +155,7 @@ export const textMessageAgent = new Agent({
 
     Always return exactly 5-8 messages in the messages array.
   `,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'agent-storage',

package/.docs/guides/migrations/agentnetwork.md

@@ -27,7 +27,7 @@ const agent = new AgentNetwork({
   name: 'agent-network',
   agents: [agent1, agent2],
   tools: { tool1, tool2 },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
 })
 
@@ -47,7 +47,7 @@ const agent = new Agent({
   name: 'agent-network',
   agents: { agent1, agent2 },
   tools: { tool1, tool2 },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
   memory,
 })
@@ -68,7 +68,7 @@ const agent = new NewAgentNetwork({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
 })
 
@@ -88,7 +88,7 @@ const agent = new Agent({
   agents: { agent1, agent2 },
   workflows: { workflow1 },
   tools: { tool1, tool2 },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
   memory,
 })

package/.docs/guides/migrations/upgrade-to-v1/agent.md

@@ -227,7 +227,7 @@ const agent = new Agent({
 +   id: 'my-agent',
     name: 'My Agent',
     instructions: 'You are a helpful assistant',
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
   });
 ```
 

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -159,7 +159,7 @@ The following options are available in the standard `.stream()` and `generate()`
           name: z.string(),
           age: z.number(),
         }),
-        model: 'openai/gpt-5.4', // Optional model override for structuring
+        model: 'openai/gpt-5.5', // Optional model override for structuring
         errorStrategy: 'fallback',
         fallbackValue: { name: 'unknown', age: 0 },
         instructions: 'Extract user information', // Override default structuring instructions
@@ -299,7 +299,7 @@ The following options are available in the standard `.stream()` and `generate()`
       schema: z.object({
         summary: z.string(),
       }),
-      model: 'openai/gpt-5.4',
+      model: 'openai/gpt-5.5',
     },
   })
   ```

package/.docs/models/embeddings.md

@@ -40,12 +40,12 @@ const embedder = new ModelRouterEmbeddingModel("google/gemini-embedding-001");
 The model router automatically detects API keys from environment variables:
 
 - **OpenAI**: `OPENAI_API_KEY`
-- **Google**: `GOOGLE_GENERATIVE_AI_API_KEY`
+- **Google**: `GOOGLE_API_KEY` (falls back to `GOOGLE_GENERATIVE_AI_API_KEY`)
 
 ```bash
 # .env
 OPENAI_API_KEY=sk-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
+GOOGLE_API_KEY=...
 ```
 
 ## Custom Providers

package/.docs/reference/agents/agent.md

@@ -16,7 +16,7 @@ export const agent = new Agent({
   id: 'test-agent',
   name: 'Test Agent',
   instructions: 'You are a helpful assistant that provides concise answers.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 // System message object
@@ -27,7 +27,7 @@ export const agent2 = new Agent({
     role: 'system',
     content: 'You are an expert programmer',
   },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 // Array of system messages
@@ -38,7 +38,7 @@ export const agent3 = new Agent({
     { role: 'system', content: 'You are a helpful assistant' },
     { role: 'system', content: 'You have expertise in TypeScript' },
   ],
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 
@@ -61,7 +61,7 @@ export const agent = new Agent({
       },
     },
   },
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 
@@ -96,9 +96,9 @@ export const agent = new Agent({
 
 ## Thread signals
 
-Use Agent signals to send real-time context into a memory thread. Signals are useful when a user adds input while an agent is already streaming, or when another process needs to add structured context to the thread.
+Use Agent signals to send real-time input and context into a memory thread. Message APIs are for user-authored input. `sendSignal()` is the lower-level API for system-generated context.
 
-A `user-message` signal represents user input. When the target thread is running, Mastra delivers the signal into the active agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input by default.
+When the target thread is running, `sendMessage()` delivers the message into the active agent loop. When the thread is idle, Mastra starts a stream with the message as the first input by default.
 
 ```typescript
 const subscription = await agent.subscribeToThread({
@@ -112,26 +112,22 @@ void (async () => {
   }
 })()
 
-agent.sendSignal(
-  { type: 'user-message', contents: 'Use the latest customer note too.' },
-  {
-    resourceId: 'user-123',
-    threadId: 'thread-abc',
-    ifIdle: {
-      streamOptions: {
-        maxSteps: 3,
-      },
+agent.sendMessage('Use the latest customer note too.', {
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    streamOptions: {
+      maxSteps: 3,
     },
   },
-)
+})
 ```
 
-Use `attributes` to identify different users in a shared thread. The signal type and attributes are rendered as XML so the model can distinguish who said what:
+Use `attributes` to identify different users in a shared thread. The attributes are rendered as XML so the model can distinguish who said what:
 
 ```typescript
-agent.sendSignal(
+agent.sendMessage(
   {
-    type: 'user',
     contents: 'Can we simplify the API surface?',
     attributes: { name: 'Devin', from: 'slack' },
   },
@@ -147,11 +143,44 @@ The model receives this as:
 
 The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
 
+### `sendMessage(message, options)`
+
+Sends a user message to an active run or memory thread. Use this when the active agent should receive the message immediately.
+
+**message** (`string | Array<TextPart | FilePart> | { contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): User-authored input. Bare strings and parts without attributes are sent to the model as normal user input. When \`attributes\` are present, Mastra renders the message as a \`\<user>\` XML element with the attributes included.
+
+**options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
+
+**options.resourceId** (`string`): Resource ID for the memory thread. Required with \`threadId\` for thread-targeted messages.
+
+**options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted messages.
+
+**options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`. Mastra uses the top-level \`resourceId\` and \`threadId\` for memory context.
+
+Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory.
+
+### `queueMessage(message, options)`
+
+Queues a user message for the next turn on a thread. If the thread is active, Mastra waits for the active run to finish, then starts a new run with the queued message. If the thread is idle, Mastra starts a run immediately.
+
+```typescript
+agent.queueMessage('Also check whether the tests need updates.', {
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+```
+
+`queueMessage()` accepts the same `message` and `options` shape as `sendMessage()` and returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`.
+
 ### `sendSignal(signal, options)`
 
 Sends a signal to an active run or memory thread.
 
-**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Signal context to send to the thread. \`type\` is the semantic signal category. \`tagName\` controls the XML tag the model sees. For example, \`{ type: 'notification', tagName: 'github-review' }\` renders as \`\<github-review>...\</github-review>\`. Legacy \`user-message\` and \`system-reminder\` payloads are still accepted and normalized. Unknown \`type\` values are rejected; use \`tagName\` for custom XML tags.
 
 **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
 
@@ -169,7 +198,7 @@ Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?
 
 ### `subscribeToThread(options)`
 
-Subscribes to raw stream chunks for a memory thread. Use this before calling `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
+Subscribes to raw stream chunks for a memory thread. Use this before calling `sendMessage()`, `queueMessage()`, or `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
 
 **options.resourceId** (`string`): Resource ID for the memory thread.
 
@@ -229,6 +258,16 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **requestContextSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
 
+**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Controls which fields the editor can override for this code-defined agent. Omit to allow editing instructions and tools. See Editor overrides below.
+
+## Editor overrides
+
+When you register the [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor), the `editor` field controls which parts of a code-defined agent can be changed through the editor. Fields owned by code are read-only in Studio and are stripped from saved overrides.
+
+**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Omit to allow editing instructions and tools. Set to \`false\` to lock the agent. Set \`instructions: true\` to allow instruction edits. Set \`tools: true\` to allow tool membership and description edits, or \`tools: { description: true }\` to allow only description edits.
+
+The agent's `id`, `name`, and `model` always come from code and can't be overridden through the editor. See the [Editor overview](https://mastra.ai/docs/editor/overview) for usage.
+
 ## Returns
 
 **agent** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.

package/.docs/reference/agents/channels.md

@@ -15,7 +15,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You are a helpful support assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -41,10 +41,12 @@ export const supportAgent = new Agent({
 
 **userName** (`string`): Bot display name shown in platform messages. Defaults to the agent's \`name\`, or \`'Mastra'\` if no name is set. (Default: `` agent's `name` ``)
 
-**threadContext** (`{ maxMessages?: number }`): Fetch recent messages from the platform when the agent is first mentioned in a thread. Set \`maxMessages: 0\` to disable. Only applies to non-DM threads. (Default: `{ maxMessages: 10 }`)
+**threadContext** (`{ maxMessages?: number; addSystemMessage?: boolean }`): How the agent picks up context about the current thread. \`maxMessages\` controls how many recent platform messages are fetched on first mention (set to \`0\` to disable; only applies to non-DM threads). \`addSystemMessage: false\` skips the built-in system message that tells the agent which channel/platform a request came from. (Default: `{ maxMessages: 10, addSystemMessage: true }`)
 
 **chatOptions** (`Omit<ChatConfig, 'adapters' | 'state' | 'userName'>`): Additional options passed directly to the \[Chat SDK]\(https\://chat-sdk.dev/docs/usage). Use for advanced configuration such as \`dedupeTtlMs\`, \`fallbackStreamingPlaceholderText\`, \`lockScope\`, and \`messageHistory\`.
 
+**resolveResourceId** (`(ctx: ResolveResourceIdContext) => string | Promise<string>`): Decide which \`resourceId\` owns resource-level memory for a channel thread, separately from who sent the message. Runs only when a new thread is created; reused threads keep their stored owner and never call the hook. Return \`ctx.defaultResourceId\` (\`${platform}:${message.author.userId}\`) to keep the built-in behavior.
+
 ## Per-adapter options
 
 Wrap an adapter in a `ChannelAdapterConfig` object to set per-adapter options:
@@ -57,7 +59,7 @@ import { createSlackAdapter } from '@chat-adapter/slack'
 const agent = new Agent({
   name: 'Example',
   instructions: '...',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       discord: {
@@ -112,7 +114,7 @@ import { createSlackAdapter } from '@chat-adapter/slack'
 const agent = new Agent({
   name: 'Streaming Agent',
   instructions: '...',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       slack: {
@@ -139,7 +141,7 @@ import { createDiscordAdapter } from '@chat-adapter/discord'
 const agent = new Agent({
   name: 'Custom Typing Agent',
   instructions: '...',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       discord: {
@@ -171,7 +173,7 @@ import { createSlackAdapter } from '@chat-adapter/slack'
 const agent = new Agent({
   name: 'Custom Handler Agent',
   instructions: '...',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -203,6 +205,46 @@ type ChannelHandler = (
 ) => Promise<void>
 ```
 
+## Resource ID resolution
+
+By default a channel thread's memory `resourceId` is `${platform}:${message.author.userId}`. The sender owns the memory, scoped per platform. For apps with a shared identity, such as single sign-on (SSO), this splits memory: the same user gets `feishu:user_123` in a Feishu DM but `user_123` on the web.
+
+Pass `resolveResourceId` to decide memory ownership separately from the sender. It runs only when a new thread is created. Reused threads keep their stored `resourceId` and never call the hook, so existing conversations don't depend on the resolver being available. Return `ctx.defaultResourceId` to fall back to the built-in behavior.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+const agent = new Agent({
+  name: 'SSO Agent',
+  instructions: '...',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    resolveResourceId: async ({ thread, message }) => {
+      // DM: share resource-level memory with the web app by using the bare SSO id
+      if (thread.isDM) {
+        return await resolveSsoUserId(message)
+      }
+      // Group chat: the conversation owns the memory; the sender stays the actor
+      return thread.channelId
+    },
+  },
+})
+```
+
+The `ResolveResourceIdContext` passed to the function:
+
+**platform** (`string`): Platform name (e.g. \`slack\`, \`discord\`).
+
+**thread** (`Thread`): The channel thread the message arrived on. Use \`thread.isDM\` to tell DMs apart from group/channel threads.
+
+**message** (`Message`): The incoming message. \`message.author.userId\` is the actor/sender, not necessarily the memory owner.
+
+**defaultResourceId** (`string`): The built-in default (\`${platform}:${message.author.userId}\`). Return this to keep the current behavior.
+
 ## Inline media
 
 Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that do not match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.

package/.docs/reference/agents/generateLegacy.md

@@ -195,7 +195,7 @@ await agent.generateLegacy(
         sentiment: z.enum(['positive', 'negative', 'neutral']),
         confidence: z.number(),
       }),
-      model: 'openai/gpt-5.4',
+      model: 'openai/gpt-5.5',
       errorStrategy: 'warn',
     },
     // Output processors for response validation

package/.docs/reference/agents/getLLM.md

@@ -10,7 +10,7 @@ await agent.getLLM()
 
 ```typescript
 await agent.getLLM({
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 
@@ -31,7 +31,7 @@ await agent.getLLM({
 ```typescript
 await agent.getLLM({
   requestContext: new RequestContext(),
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 

package/.docs/reference/agents/getMetadata.md

@@ -29,7 +29,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You help customers with support requests.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   metadata: { type: 'support' },
 })
 
@@ -45,7 +45,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You help customers with support requests.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   metadata: ({ requestContext }) => ({
     type: 'support',
     tenant: requestContext.get('tenant'),

package/.docs/reference/agents/network.md

@@ -16,7 +16,7 @@ const agent = new Agent({
   id: 'network-agent',
   name: 'Network Agent',
   instructions: 'You are a network agent that can help users with a variety of tasks.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     agent1,
     agent2,

package/.docs/reference/browser/agent-browser.md

@@ -21,7 +21,7 @@ export const browserAgent = new Agent({
   name: 'Browser Agent',
   instructions: `You can browse the web. Use browser_snapshot to see the page structure,
 then interact with elements using their refs (e.g., @e5).`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
 })
 ```

package/.docs/reference/browser/browser-viewer.md

@@ -23,7 +23,7 @@ const workspace = new Workspace({
 
 const browserAgent = new Agent({
   id: 'browser-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workspace,
   instructions: 'You are a web automation assistant.',
 })

package/.docs/reference/browser/mastra-browser.md

@@ -24,7 +24,7 @@ export const browserAgent = new Agent({
   id: 'browser-agent',
   name: 'Browser Agent',
   instructions: 'You can browse the web to find information.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
 })
 ```

package/.docs/reference/browser/stagehand-browser.md

@@ -12,7 +12,7 @@ import { StagehandBrowser } from '@mastra/stagehand'
 
 const browser = new StagehandBrowser({
   headless: true,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   selfHeal: true,
 })
 
@@ -22,7 +22,7 @@ export const browserAgent = new Agent({
   instructions: `You can browse the web using natural language.
 Use stagehand_act to perform actions like "click the login button".
 Use stagehand_extract to get data from pages.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
 })
 ```
@@ -39,7 +39,7 @@ Use stagehand_extract to get data from pages.`,
 
 **projectId** (`string`): Browserbase project ID. Required when env is 'BROWSERBASE'.
 
-**model** (`string | ModelConfiguration`): Model configuration for AI operations. Can be a string like '\_\_GATEWAY\_OPENAI\_MODEL\_\_' or an object with modelName, apiKey, and baseURL. (Default: `'openai/gpt-5.4'`)
+**model** (`string | ModelConfiguration`): Model configuration for AI operations. Can be a string like 'openai/gpt-5.5' or an object with modelName, apiKey, and baseURL. (Default: `'openai/gpt-5.5'`)
 
 **selfHeal** (`boolean`): Enable self-healing selectors. When enabled, Stagehand uses AI to find elements even when initial selectors fail. (Default: `true`)
 
@@ -268,7 +268,7 @@ const browser = new StagehandBrowser({
   env: 'BROWSERBASE',
   apiKey: process.env.BROWSERBASE_API_KEY,
   projectId: process.env.BROWSERBASE_PROJECT_ID,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 
@@ -279,7 +279,7 @@ Configure the AI model for Stagehand operations:
 ```typescript
 // String format: "provider/model"
 const browser = new StagehandBrowser({
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 // Object format for custom configuration