@mastra/mcp-docs-server 1.1.42-alpha.8 → 1.1.43-alpha.0

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/reference/acp/acp-agent.md

@@ -0,0 +1,228 @@
+# AcpAgent class
+
+The `AcpAgent` class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection, code edits, or other ACP-backed tasks to a named subagent.
+
+If you want the parent agent to call the ACP agent as a tool instead, use [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool).
+
+## Usage example
+
+Register an ACP-compatible coding agent in a parent agent's `agents` map:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  description: 'An ACP-compatible coding agent that can inspect and edit files',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent subagent.',
+  model: 'openai/gpt-5.5',
+  agents: {
+    codeAgent,
+  },
+})
+```
+
+For Claude Code, ACP support is provided by the `@agentclientprotocol/claude-agent-acp` bridge package. Configure the ACP agent command to run the bridge, then select a Claude model after session creation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const claudeCodeAgent = new AcpAgent({
+  id: 'claude-code-agent',
+  name: 'Claude Code Agent',
+  description: 'Use Claude Code through ACP.',
+  command: 'npx',
+  args: ['@agentclientprotocol/claude-agent-acp'],
+  cwd: process.cwd(),
+  model: 'claude-sonnet-4-6',
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the subagent.
+
+**name** (`string`): Display name used during agent delegation. Defaults to \`id\`.
+
+**description** (`string`): Description shown to the model when it can delegate to this subagent.
+
+**command** (`string`): ACP agent executable to spawn.
+
+**args** (`string[]`): Arguments passed to the ACP agent executable. (Default: `[]`)
+
+**env** (`Record<string, string>`): Environment variables to merge with the current process environment when spawning the ACP process.
+
+**cwd** (`string`): Working directory for the ACP process and ACP session. Also used as the default local filesystem base path. (Default: `process.cwd()`)
+
+**session** (`Partial<NewSessionRequest>`): ACP session creation options. Defaults to \`cwd\` or \`process.cwd()\` and an empty MCP server list.
+
+**initialize** (`Partial<InitializeRequest>`): ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.
+
+**authMethodId** (`string`): ACP authentication method ID to invoke after initialization and before session creation.
+
+**persistSession** (`boolean`): Whether to keep the ACP process and session alive after each prompt. Set to \`false\` to stop the process after each prompt completes. (Default: `true`)
+
+**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
+
+**workspace** (`Workspace`): Workspace used for ACP file read and write requests. Defaults to a \`Workspace\` backed by \`LocalFilesystem\` at \`cwd\` or \`process.cwd()\`.
+
+**model** (`ModelId`): Model ID to select after ACP session creation using the ACP \`session/set\_model\` method.
+
+## Properties
+
+**id** (`TId`): Readonly subagent identifier from the constructor options.
+
+**name** (`string`): Readonly display name for this subagent.
+
+**description** (`string`): Readonly description shown when the parent agent can delegate to this subagent.
+
+**connection** (`ACPConnection`): Readonly ACP connection used to start the agent process, create sessions, send prompts, stream updates, and manage models.
+
+## Methods
+
+### Generation
+
+#### `generate(messages, options?)`
+
+Sends the prompt to the ACP agent, buffers text chunks from the ACP response, and returns a Mastra subagent generate result.
+
+```typescript
+const result = await codeAgent.generate('Inspect the repository and summarize the test setup')
+
+console.log(result.text)
+```
+
+#### `stream(messages, options?)`
+
+Sends the prompt to the ACP agent and returns a Mastra subagent stream result. ACP `agent_message_chunk` updates are emitted as Mastra `text-delta` chunks.
+
+```typescript
+const result = await codeAgent.stream('Refactor the selected module and explain each change')
+
+for await (const chunk of result.fullStream) {
+  if (chunk.type === 'text-delta') {
+    process.stdout.write(chunk.payload.text)
+  }
+}
+```
+
+`resumeGenerate()` and `resumeStream()` are not supported and throw an error when called.
+
+### Model management
+
+#### `getAvailableModels()`
+
+Starts the ACP process if needed and returns the model list advertised by the ACP session.
+
+```typescript
+const models = await codeAgent.getAvailableModels()
+// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]
+```
+
+#### `setModel(modelId)`
+
+Selects a model for the active ACP session. If the ACP agent advertises available models, the model ID must match one of them.
+
+```typescript
+await codeAgent.setModel('claude-sonnet-4-6')
+```
+
+## Session lifecycle
+
+`AcpAgent` starts the configured `command` on first use, initializes the ACP client, and creates an ACP session. By default, `persistSession` is `true`, so the process and session stay alive across `generate()`, `stream()`, `getAvailableModels()`, and `setModel()` calls.
+
+Set `persistSession: false` when each prompt should run in a fresh ACP process:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP coding task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+})
+```
+
+With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+
+## Workspace integration
+
+ACP file operations go through Mastra's `Workspace` abstraction. If you do not pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` or `process.cwd()` as the filesystem base path.
+
+Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: process.cwd(),
+  }),
+})
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run coding tasks in a controlled workspace',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  workspace,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `AcpAgent` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+Pass `onPermissionRequest` to inspect the request and return your own permission response:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Related
+
+- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
+- [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/reference/acp/create-acp-tool.md

@@ -0,0 +1,131 @@
+# createACPTool()
+
+The `createACPTool()` function creates a Mastra tool that sends a `task` string to an Agent Client Protocol (ACP)-compatible coding agent and returns the final ACP response as `output`. Use it when a parent agent should decide when to call the ACP agent as a tool.
+
+If you want to register the ACP agent as a Mastra subagent instead, use the [`AcpAgent` class](https://mastra.ai/reference/acp/acp-agent).
+
+## Usage example
+
+Create a code editing tool and register it on a parent agent:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to inspect and edit code',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    codeAgentTool,
+  },
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for the Mastra tool.
+
+**description** (`string`): Description shown to the model when it can call this tool.
+
+**command** (`string`): ACP agent executable to spawn.
+
+**args** (`string[]`): Arguments passed to the ACP agent executable. (Default: `[]`)
+
+**env** (`Record<string, string>`): Environment variables to merge with the current process environment when spawning the ACP process.
+
+**cwd** (`string`): Working directory for the ACP process and ACP session. Also used as the default local filesystem base path. (Default: `process.cwd()`)
+
+**session** (`Partial<NewSessionRequest>`): ACP session creation options. Defaults to \`cwd\` or \`process.cwd()\` and an empty MCP server list.
+
+**initialize** (`Partial<InitializeRequest>`): ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.
+
+**authMethodId** (`string`): ACP authentication method ID to invoke after initialization and before session creation.
+
+**persistSession** (`boolean`): Whether the ACP connection created for a tool execution disconnects after the prompt. Set to \`false\` to stop the process after each prompt completes. (Default: `true`)
+
+**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
+
+**workspace** (`Workspace`): Workspace option from the shared ACP connection options. During tool execution, \`createACPTool()\` passes the current Mastra workspace from the execution context when one is available; otherwise the ACP connection falls back to a local filesystem workspace. Use \`AcpAgent\` when you need to provide an explicit workspace instance.
+
+**model** (`ModelId`): Model ID to select after ACP session creation using the ACP \`session/set\_model\` method.
+
+## Input schema
+
+**task** (`string`): The task to send to the ACP agent.
+
+## Output schema
+
+**output** (`string`): The final text output returned by the ACP agent.
+
+## Suspend and resume schema
+
+`createACPTool()` defines suspend and resume schemas for permission request payloads. Permission decisions are returned through `onPermissionRequest`; by default, `@mastra/acp` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+### Suspend payload
+
+**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): Permission request title and selectable options returned by the ACP agent.
+
+### Resume payload
+
+**optionId** (`string`): Permission option ID to select when resuming with \`outcome: "selected"\`.
+
+**outcome** (`"selected" | "cancelled"`): Permission decision used to continue or cancel the ACP request.
+
+## Session lifecycle
+
+Each tool execution creates an ACP connection, starts the configured `command`, initializes the ACP client, creates an ACP session, and sends the `task` with ACP `session/prompt`.
+
+By default, `persistSession` is `true` for the ACP connection created during tool execution. Set `persistSession: false` when the ACP process should stop as soon as that prompt completes.
+
+Use [`AcpAgent`](https://mastra.ai/reference/acp/acp-agent) when you need a reusable ACP subagent instance with explicit session lifecycle control across calls.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+Pass `onPermissionRequest` to inspect the request and return your own permission response:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+
+export const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Related
+
+- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
+- [AcpAgent class reference](https://mastra.ai/reference/acp/acp-agent)
+- [Tool reference](https://mastra.ai/reference/tools/create-tool)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

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',
 })
 ```
 
@@ -141,7 +141,7 @@ The model receives this as:
 <user name="Devin" from="slack">Can we simplify the API surface?</user>
 ```
 
-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).
+The UI sees the message contents and 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)`
 
@@ -196,6 +196,54 @@ Sends a signal to an active run or memory thread.
 
 Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory.
 
+### `sendNotificationSignal(notification, options)`
+
+Creates or coalesces a notification inbox record, resolves the notification delivery policy, and sends a notification signal when the decision is immediate.
+
+```typescript
+const result = await agent.sendNotificationSignal(
+  {
+    source: 'github',
+    kind: 'ci-status',
+    priority: 'high',
+    summary: 'CI failed on main: 3 tests failed.',
+    dedupeKey: 'github:acme/app:main:ci',
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+  },
+)
+```
+
+**notification.source** (`string`): External system that produced the notification, such as \`github\`, \`slack\`, or \`email\`.
+
+**notification.kind** (`string`): Notification kind within the source, such as \`ci-status\`, \`mention\`, or \`direct-message\`.
+
+**notification.summary** (`string`): LLM-facing summary used as the notification signal contents.
+
+**notification.priority** (`'low' | 'medium' | 'high' | 'urgent'`): Priority used by the notification delivery policy. Defaults to \`medium\`.
+
+**notification.payload** (`unknown`): Structured payload stored on the inbox record for tools or application code.
+
+**notification.dedupeKey** (`string`): Key used to coalesce duplicate pending notifications from the same source and thread.
+
+**notification.coalesceKey** (`string`): Key used to combine related pending notifications from the same source and thread.
+
+**notification.attributes** (`Record<string, JSONValue>`): Extra attributes copied onto the emitted notification signal.
+
+**notification.metadata** (`Record<string, unknown>`): Application metadata stored on the inbox record.
+
+**options.resourceId** (`string`): Resource ID for the notification inbox and target memory thread.
+
+**options.threadId** (`string`): Thread ID for the notification inbox and target memory thread.
+
+**options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when an immediate notification wakes an idle thread.
+
+Returns `{ accepted: true, record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void> }`. `record` is the stored inbox record. `decision` is the delivery-policy result. `signal` and `runId` are present when ingress emits a signal immediately, including the immediate summary emitted for active high-priority notifications. `persisted` is present when the emitted signal is persisted without waking an idle thread.
+
+Default delivery is priority-aware. `urgent` notifications deliver immediately. `high` notifications deliver immediately when the thread is idle; when the thread is active, Mastra emits a summary immediately and keeps `deliverAt` for later full delivery when the thread is idle. `medium` notifications deliver immediately when idle and batch into summaries when active. `low` notifications batch into summaries in both active and idle threads; idle low-priority summaries reach subscribers without waking the model loop. For the full flow, visit [Signals](https://mastra.ai/docs/agents/signals).
+
 ### `subscribeToThread(options)`
 
 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.
@@ -234,6 +282,8 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **transform** (`ToolPayloadTransformPolicy`): Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool \`transform\` on \`createTool()\` for tool-local rules.
 
+**notifications** (`{ deliveryPolicy?: NotificationDeliveryPolicyConfig }`): Notification delivery configuration for \`sendNotificationSignal()\`. \`deliveryPolicy\` can define \`decide\`, \`sources\`, \`priorities\`, or \`default\` rules that return \`deliver\`, \`queue\`, \`defer\`, \`summarize\`, \`persist\`, or \`discard\` decisions.
+
 **workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
 
 **defaultOptions** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): Default options used when calling \`stream()\` and \`generate()\`.

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(),
@@ -45,6 +45,8 @@ export const supportAgent = new Agent({
 
 **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.