@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.3

package/.docs/models/providers/modal.md

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Modal logo](https://models.dev/logos/modal.svg)Modal
+
+Access 1 Modal model through Mastra's model router. Authentication is handled automatically using the `MODAL_PROXY_TOKEN` environment variable.
+
+Learn more in the [Modal documentation](https://modal.com/docs/guide/endpoints).
+
+```bash
+MODAL_PROXY_TOKEN=your-api-token
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "modal/thinkingmachines/Inkling-NVFP4"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Modal documentation](https://modal.com/docs/guide/endpoints) for details.
+
+## Models
+
+| Model                                  | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `modal/thinkingmachines/Inkling-NVFP4` | 1.0M    |       |           |       |       |       | $1         | $5          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://inference.us-west.modal.direct/v1",
+    id: "modal/thinkingmachines/Inkling-NVFP4",
+    apiKey: process.env.MODAL_PROXY_TOKEN,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "modal/thinkingmachines/Inkling-NVFP4"
+      : "modal/thinkingmachines/Inkling-NVFP4";
+  }
+});
+```

package/.docs/models/providers/wandb.md

@@ -2,7 +2,7 @@
 
 # ![Weights & Biases logo](https://models.dev/logos/wandb.svg)Weights & Biases
 
-Access 30 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
+Access 31 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
 
 Learn more in the [Weights & Biases documentation](https://docs.wandb.ai).
 
@@ -50,6 +50,7 @@ for await (const chunk of stream) {
 | `wandb/moonshotai/Kimi-K2.5`                         | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `wandb/moonshotai/Kimi-K2.6`                         | 262K    |       |           |       |       |       | $0.65      | $3          |
 | `wandb/moonshotai/Kimi-K2.7-Code`                    | 262K    |       |           |       |       |       | $0.71      | $4          |
+| `wandb/moonshotai/Kimi-K3`                           | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `wandb/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8` | 262K    |       |           |       |       |       | $0.20      | $0.80       |
 | `wandb/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B`     | 262K    |       |           |       |       |       | $0.75      | $3          |
 | `wandb/openai/gpt-oss-120b`                          | 131K    |       |           |       |       |       | $0.03      | $0.17       |

package/.docs/models/providers.md

@@ -89,6 +89,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [MiniMax Token Plan (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn-coding-plan)
 - [Mixlayer](https://mastra.ai/models/providers/mixlayer)
 - [Moark](https://mastra.ai/models/providers/moark)
+- [Modal](https://mastra.ai/models/providers/modal)
 - [Model Oracle AI](https://mastra.ai/models/providers/model-oracle-ai)
 - [ModelScope](https://mastra.ai/models/providers/modelscope)
 - [Moonshot AI](https://mastra.ai/models/providers/moonshotai)

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

@@ -2,7 +2,7 @@
 
 # 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.
+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 and code edits. It can also delegate other ACP-backed tasks to the 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).
 
@@ -27,7 +27,7 @@ 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',
+  model: 'openai/gpt-5.6-sol',
   agents: {
     codeAgent,
   },
@@ -143,7 +143,7 @@ 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.
+`AcpAgent` starts the configured `command` on first use and initializes the ACP client. It then 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:
 
@@ -220,7 +220,7 @@ export const codeAgent = new AcpAgent({
 })
 ```
 
-Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+Use this callback to enforce local policy or inspect the permission title. It can also route the decision to your own approval flow.
 
 ## Related
 

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

@@ -26,7 +26,7 @@ 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',
+  model: 'openai/gpt-5.6-sol',
   tools: {
     codeAgentTool,
   },
@@ -87,7 +87,7 @@ export const codeSupervisor = new Agent({
 
 ## 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`.
+Each tool execution creates an ACP connection and starts the configured `command`. It initializes the ACP client and creates an ACP session before sending 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.
 
@@ -124,7 +124,7 @@ export const codeAgentTool = createACPTool({
 })
 ```
 
-Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+Use this callback to enforce local policy or inspect the permission title. It can also route the decision to your own approval flow.
 
 ## Extension methods
 

package/.docs/reference/agent-controller/agent-controller-class.md

@@ -4,9 +4,9 @@
 
 > **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-The `AgentController` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
+The `AgentController` class coordinates agent modes with shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive. The layer manages threads and model or mode switches. It sends messages and handles tool approvals while tracking events.
 
-Per-conversation state — identity, the active thread, mode and model selection, run state, grants, and the display snapshot — lives on the [`Session`](https://mastra.ai/reference/agent-controller/session), accessed through `agentController.session`.
+Per-conversation state (identity, the active thread, mode and model selection, run state, grants, and the display snapshot) lives on the [`Session`](https://mastra.ai/reference/agent-controller/session), accessed through `agentController.session`.
 
 For a conceptual introduction, see the [AgentController overview](https://mastra.ai/docs/agent-controller/overview).
 
@@ -84,7 +84,7 @@ await agentController.sendMessage({ content: 'Hello!' })
 
 **modes.additionalTools** (`ToolsInput`): Tools layered on top of the backing agent's tools. Mutually exclusive with tools.
 
-**modes.availableTools** (`string[]`): Per-mode tool visibility allowlist. When set, only tools whose final exposed names appear in this list are visible to the model and executable during this mode's runs. undefined = all tools visible; \[] = no tools. Per-tool and per-category deny rules take precedence over this list. Workspace tools use the same list — reference them by exposed names (view, write\_file, etc.).
+**modes.availableTools** (`string[]`): Per-mode tool visibility allowlist. When set, only tools whose final exposed names appear in this list are visible to the model and executable during this mode's runs. undefined = all tools visible; \[] = no tools. Per-tool and per-category deny rules take precedence over this list. Workspace tools use the same list: reference them by exposed names (view, write\_file, etc.).
 
 **modes.agent** (`Agent`): The agent for this mode. Deprecated in favor of the top-level agent config with mode-level overrides.
 
@@ -164,7 +164,7 @@ await agentController.sendMessage({ content: 'Hello!' })
 
 #### `init()`
 
-Initialize the agentController. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts interval handlers. Call this before using the agentController.
+Initialize the agentController. Loads storage, initializes a static workspace (runtime-defined factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts interval handlers. Call this before using the agentController.
 
 ```typescript
 await agentController.init()
@@ -174,11 +174,11 @@ await agentController.init()
 
 Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the AgentController's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage is ready.
 
-The AgentController owns no session of its own — every consumer creates its own session and drives all work through it. A `resourceId` maps to exactly one session per AgentController (get-or-create): calling `createSession` with the same `resourceId` returns the existing session, so reconnects resume rather than fork the conversation. Different `resourceId`s produce independent sessions with isolated event bus, mode, model, state, and current thread. Use `session.thread.create()` and `session.thread.switch()` to manage multiple conversations within one session.
+The AgentController owns no session of its own: every consumer creates its own session and drives all work through it. A `resourceId` maps to exactly one session per AgentController (get-or-create): calling `createSession` with the same `resourceId` returns the existing session, so reconnects resume rather than fork the conversation. Different `resourceId`s produce independent sessions with isolated event bus, mode, model, state, and current thread. Use `session.thread.create()` and `session.thread.switch()` to manage multiple conversations within one session.
 
-`id` and `ownerId` are required — they mirror `SessionRecord.id` and `SessionRecord.ownerId` and are stable for the life of the session. `resourceId` is optional and defaults to `config.resourceId` then `config.id`.
+`id` and `ownerId` are required: they mirror `SessionRecord.id` and `SessionRecord.ownerId` and are stable for the life of the session. `resourceId` is optional and defaults to `config.resourceId` then `config.id`.
 
-Each session owns its own `Workspace` and `Browser` instance. When `workspace` is omitted, the AgentController resolves its configured workspace (a static instance or a dynamic factory) and passes it to the session. Pass a `workspace` override to give a specific session a different workspace than the AgentController default. The workspace is initialized during session creation; `workspace_ready` and `workspace_status_changed` events are emitted on the session bus after `init()` completes, and late subscribers receive a replay of the last workspace status.
+Each session owns its own `Workspace` and `Browser` instance. When `workspace` is omitted, the AgentController resolves its configured workspace (a static instance or a runtime-defined factory) and passes it to the session. Pass a `workspace` override to give a specific session a different workspace than the AgentController default. The workspace is initialized during session creation; `workspace_ready` and `workspace_status_changed` events are emitted on the session bus after `init()` completes, and late subscribers receive a replay of the last workspace status.
 
 ```typescript
 const session = await agentController.createSession({
@@ -270,7 +270,7 @@ const mastra = agentController.getMastra()
 
 #### `getWorkspace()`
 
-Return the AgentController-level workspace if it's a static `Workspace` instance. Dynamic factory workspaces aren't resolved here — use [`resolveWorkspace()`](#resolveworkspace-session-requestcontext-) to resolve a factory against a session's request context.
+Return the AgentController-level workspace if it's a static `Workspace` instance. Dynamic factory workspaces aren't resolved here: use [`resolveWorkspace()`](#resolveworkspace-session-requestcontext-) to resolve a factory against a session's request context.
 
 ```typescript
 const workspace = agentController.getWorkspace()
@@ -278,7 +278,7 @@ const workspace = agentController.getWorkspace()
 
 #### `resolveWorkspace({ session, requestContext? })`
 
-Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory against the given session's request context and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
+Eagerly resolve and cache the workspace. For runtime-defined workspaces (factory function), this triggers the factory against the session's request context and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
 
 ```typescript
 const workspace = await agentController.resolveWorkspace({ session })
@@ -292,7 +292,7 @@ const workspace = await agentController.resolveWorkspace({ session, requestConte
 
 #### `hasWorkspace()`
 
-Whether a workspace is configured on this AgentController (static instance or dynamic factory). Sessions without an explicit workspace override fall back to this.
+Whether a workspace is configured on this AgentController (static instance or runtime-defined factory). Sessions without an explicit workspace override fall back to this.
 
 ```typescript
 if (agentController.hasWorkspace()) {
@@ -346,11 +346,11 @@ const models = await agentController.listAvailableModels()
 
 ### Threads
 
-The agentController owns thread lifecycle transitions — creating, switching, cloning, renaming, and deleting threads — because they coordinate the shared thread lock and emit events. The active thread binding and thread/message reads live on [`session.thread`](https://mastra.ai/reference/agent-controller/session).
+The agentController owns thread lifecycle transitions (creating, switching, cloning, renaming, and deleting threads) because they coordinate the shared thread lock and emit events. The active thread binding and thread/message reads live on [`session.thread`](https://mastra.ai/reference/agent-controller/session).
 
 #### `createThread({ title? })`
 
-Create a new thread. Initializes thread metadata, saves it to storage, acquires a thread lock, and emits a `thread_created` event.
+Creates a new thread and initializes its metadata. The method saves it to storage and acquires a thread lock before emitting a `thread_created` event.
 
 ```typescript
 const thread = await agentController.createThread({ title: 'New conversation' })
@@ -358,13 +358,13 @@ const thread = await agentController.createThread({ title: 'New conversation' })
 
 #### `switchThread({ threadId })`
 
-Switch to a different thread. Aborts any in-progress operations, acquires a lock on the new thread, releases the lock on the previous thread, loads the thread's metadata, and emits a `thread_changed` event.
+Switch to a different thread. This aborts in-progress operations and acquires a lock on the new thread. It releases the previous thread lock and loads the new thread metadata. It then emits a `thread_changed` event.
 
 ```typescript
 await agentController.switchThread({ threadId: 'thread-abc123' })
 ```
 
-To list threads from storage, use [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session). By default it returns only threads for the current resource and hides transient [forked subagent](#forked-subagents) threads; pass `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.
+To list threads from storage, use [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session). By default it returns only threads for the current resource and hides transient [forked subagent](#forked-subagents) threads. Pass `includeForkedSubagents: true` to opt back into seeing them: e.g. for a debug panel.
 
 #### `renameThread({ title })`
 
@@ -376,7 +376,7 @@ await agentController.renameThread({ title: 'Updated title' })
 
 #### `cloneThread({ sourceThreadId?, title?, resourceId? })`
 
-Clone an existing thread and switch to the clone. Copies all messages, acquires a lock on the new thread, releases the lock on the previous thread, and emits a `thread_created` event. If `sourceThreadId` is omitted, the current thread is cloned. When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, OM records are cloned with remapped message IDs.
+Clone an existing thread and switch to the clone. Copies all messages and acquires a lock on the new thread. It then releases the lock on the previous thread and emits a `thread_created` event. If `sourceThreadId` is omitted, the current thread is cloned. When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, OM records are cloned with remapped message IDs.
 
 ```typescript
 // Clone the current thread
@@ -432,7 +432,7 @@ Reading messages is owned by [`session.thread`](https://mastra.ai/reference/agen
 
 ### Memory
 
-The `memory` property bundles thread management operations into a single namespace. `memory.createThread`, `memory.switchThread`, and `memory.renameThread` delegate to the corresponding AgentController lifecycle methods documented above; `memory.listThreads` delegates to [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session).
+The `memory` property bundles thread management operations into a single namespace. `memory.createThread`, `memory.switchThread`, and `memory.renameThread` delegate to the corresponding AgentController lifecycle methods documented above. `memory.listThreads` delegates to [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session).
 
 #### `memory.deleteThread({ threadId })`
 
@@ -470,7 +470,7 @@ agentController.followUp({ content: 'Now apply those changes' })
 
 ### Tool approvals
 
-Responding to a pending tool approval is owned by the session — see [`session.respondToToolApproval()`](https://mastra.ai/reference/agent-controller/session). The agentController owns the permission _policy_ that decides when approval is required, documented under [Permissions](#permissions) below.
+Responding to a pending tool approval is owned by the session: see [`session.respondToToolApproval()`](https://mastra.ai/reference/agent-controller/session). The agentController owns the permission _policy_ that decides when approval is required, documented under [Permissions](#permissions) below.
 
 ### Tool suspensions and plans
 
@@ -478,7 +478,7 @@ Responding to a pending tool approval is owned by the session — see [`session.
 
 Respond to a pending tool suspension. Interactive built-in tools such as `ask_user` and `request_access` pause through the native tool-suspension primitive, which emits a `tool_suspended` event carrying `toolCallId`, `toolName`, and `suspendPayload`. Pass `resumeData` to resume the suspended tool with the user's response.
 
-Provide `toolCallId` to select which suspension to resume. It's required when more than one tool is suspended at the same time (for example, parallel `ask_user` calls). When omitted, it resolves to the sole pending suspension.
+Provide `toolCallId` to select which suspension to resume. It's required when more than one tool is suspended concurrently (for example, parallel `ask_user` calls). When omitted, it resolves to the sole pending suspension.
 
 ```typescript
 agentController.subscribe(event => {
@@ -558,14 +558,14 @@ The observer/reflector model selection and observation/reflection thresholds liv
 
 ### Forked subagents
 
-By default, a subagent runs with a fresh context — it doesn't see the parent conversation. **Forked subagents** opt into a different model: the subagent runs on a clone of the parent thread and reuses the parent agent's full configuration. This is useful when the subagent needs the full context of the conversation so far (e.g., recalling earlier user-supplied facts), and when prompt-cache hit rates matter.
+By default, a subagent runs with a fresh context: it doesn't see the parent conversation. **Forked subagents** opt into a different model: the subagent runs on a clone of the parent thread and reuses the parent agent's full configuration. This is useful when the subagent needs the full context of the conversation so far (e.g., recalling earlier user-supplied facts), and when prompt-cache hit rates matter.
 
 #### Enabling forked mode
 
 Set `forked: true` either on the `AgentControllerSubagent` definition (per-type default) or on each `subagent` tool call (per-invocation override):
 
 ```typescript
-// Per-type default — every call to this subagent forks unless overridden.
+// Per-type default: every call to this subagent forks unless overridden.
 const subagents: AgentControllerSubagent[] = [
   {
     id: 'collaborator',
@@ -577,20 +577,20 @@ const subagents: AgentControllerSubagent[] = [
 ]
 ```
 
-The model can also pass `forked: true` (or `forked: false`) per-invocation in the `subagent` tool input; the per-invocation value wins.
+The model can also pass `forked: true` (or `forked: false`) per-invocation in the `subagent` tool input. The per-invocation value wins.
 
 #### Semantics and constraints
 
 - **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the agentController must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
-- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedAgentControllerTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
-- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured agentController tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
+- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedAgentControllerTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode. This preserves the prompt-cache prefix.
+- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured agentController tools, _including the `subagent` tool itself_) so the LLM request prefix, system prompt + tool list + tool schemas + tool descriptions, stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
 - **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
-- **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal — the clone still runs.
+- **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal: the clone still runs.
 - **Parent thread untouched.** All subagent activity (messages, OM writes) lands on the fork. The parent thread is never appended to during a forked subagent run.
 
 #### When to prefer non-forked mode
 
-Forked mode trades isolation for context inheritance. If the subagent should run with a strictly smaller toolset, a different system prompt, or a cheaper model, use the default (non-forked) mode and pass any required context explicitly in the `task` description.
+Forked mode trades isolation for context inheritance. Use the default (non-forked) mode when the subagent needs a restricted toolset or a different system prompt. The same applies when using a cheaper model. Pass any required context explicitly in the `task` description.
 
 ### Events
 
@@ -598,7 +598,7 @@ Forked mode trades isolation for context inheritance. If the subagent should run
 
 Register an event listener. Returns an unsubscribe function.
 
-Use this method for all consumers — UI, Server-Sent Events (SSE), terminal UI (TUI), bridge rendering, audit logs, debugging, analytics, and deterministic replay. For display rendering, watch for the `display_state_changed` event and read the latest snapshot from [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session). After every event the agentController emits `display_state_changed`, so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the next snapshot.
+Use this method for all consumers: UI, Server-Sent Events (SSE), terminal UI (TUI), bridge rendering, audit logs, debugging, analytics, and deterministic replay. For display rendering, watch for the `display_state_changed` event and read the latest snapshot from [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session). After every event the agentController emits `display_state_changed`, so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the next snapshot.
 
 ```typescript
 // Render from the coalesced display-state snapshot:
@@ -694,21 +694,21 @@ The agentController emits events through registered listeners. The following tab
 | `shell_output`             | A tool emitted shell output (stdout or stderr).                                                                                                                                                                                                                                           |
 | `display_state_changed`    | The canonical `AgentControllerDisplayState` snapshot changed. Read it from [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session).                                                                                                                          |
 
-The agentController also emits low-level streaming content chunks — `text`, `thinking`, `tool_call`, `tool_result`, `image`, and `file`. These are the raw pieces that get assembled into messages; most UIs render from `message_update` (or read the [`session.displayState`](https://mastra.ai/reference/agent-controller/session) snapshot) rather than subscribing to them directly.
+The agentController also emits low-level streaming content chunks: `text`, `thinking`, `tool_call`, `tool_result`, `image`, and `file`. These are the raw pieces that get assembled into messages. Most UIs render from `message_update` (or read the [`session.displayState`](https://mastra.ai/reference/agent-controller/session) snapshot) rather than subscribing to them directly.
 
 ## Built-in tools
 
 The agentController provides built-in tools to agents in every mode:
 
-| Tool            | Description                                                                                                                                                                                          |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ask_user`      | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
-| `submit_plan`   | Submit a plan for user review and approval.                                                                                                                                                          |
-| `task_write`    | Create or replace a structured task list for tracking progress. Assigns task IDs when omitted and returns the structured task list snapshot.                                                         |
-| `task_update`   | Update one tracked task by ID and return the structured task list snapshot.                                                                                                                          |
-| `task_complete` | Mark one tracked task completed by ID and return the structured task list snapshot.                                                                                                                  |
-| `task_check`    | Check the completion status of the current task list and return `tasks`, `summary`, `incompleteTasks`, and `isError` fields.                                                                         |
-| `subagent`      | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
+| Tool            | Description                                                                                                                                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ask_user`      | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                           |
+| `submit_plan`   | Submit a plan for user review and approval.                                                                                                                                                         |
+| `task_write`    | Create or replace a structured task list for tracking progress. Assigns task IDs when omitted and returns the structured task list snapshot.                                                        |
+| `task_update`   | Update one tracked task by ID and return the structured task list snapshot.                                                                                                                         |
+| `task_complete` | Mark one tracked task completed by ID and return the structured task list snapshot.                                                                                                                 |
+| `task_check`    | Check the completion status of the current task list and return `tasks`, `summary`, `incompleteTasks`, and `isError` fields.                                                                        |
+| `subagent`      | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation. See [Forked subagents](#forked-subagents). |
 
 ### `ask_user` selections
 

package/.docs/reference/agent-controller/session.md

@@ -4,7 +4,7 @@
 
 > **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-A `Session` owns all the state tied to a single conversation. The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) is the shared host — agents, storage, config, the thread lock, and the event bus — while the `Session` holds everything that's per-conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live agent stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot.
+A `Session` owns all the state tied to a single conversation. The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) is the shared host (agents, storage, config, the thread lock, and the event bus) while the `Session` holds everything that's per-conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live agent stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot.
 
 Access the session through `agentController.session`.
 
@@ -72,7 +72,7 @@ Returns: `Workspace`
 
 ### Permissions
 
-Session-scoped grants auto-approve tools without prompting. Grants are ephemeral — they reset when the session restarts and are never persisted.
+Session-scoped grants auto-approve tools without prompting. Grants are ephemeral: they reset when the session restarts and are never persisted.
 
 #### `grantCategory(category)`
 
@@ -123,7 +123,7 @@ const runId = agentController.session.getCurrentRunId()
 
 #### `abortRun()`
 
-Abort the in-flight run: aborts the live stream, requests abort on the run, and clears parked tool suspensions.
+Abort the in-flight run: aborts the live stream and requests abort on the run. It also clears parked tool suspensions.
 
 ```typescript
 agentController.session.abortRun()
@@ -278,7 +278,7 @@ const mode = agentController.session.mode.resolve()
 
 ### `session.mode.switch({ modeId })`
 
-Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.
+Switch to a different mode. Aborts any in-progress generation and saves the current model to the outgoing mode. It then loads the incoming mode's model and emits `mode_changed` and `model_changed` events.
 
 ```typescript
 await agentController.session.mode.switch({ modeId: 'build' })
@@ -374,7 +374,7 @@ const observerModel = agentController.session.om.observer.resolvedModel()
 
 ## Permissions
 
-`session.permissions` owns the persisted tool-approval _policy_ — the per-category and per-tool rules consulted during approval resolution. These are distinct from the in-memory session _grants_ documented under [Methods → Permissions](#permissions); grants reset each session, whereas these rules are persisted in session state.
+`session.permissions` owns the persisted tool-approval _policy_: the per-category and per-tool rules consulted during approval resolution. These are distinct from the in-memory session _grants_ documented under [Methods → Permissions](#permissions); grants reset each session, whereas these rules are persisted in session state.
 
 ### `session.permissions.getRules()`
 
@@ -559,7 +559,7 @@ After every event the agentController emits `display_state_changed`, so high-fre
 
 ## State
 
-`session.state` owns the schema-validated AgentController state for the conversation. It holds the current snapshot, validates updates against the `stateSchema` passed to the AgentController, serializes concurrent writes, and emits a `state_changed` event on every change.
+`session.state` owns the schema-validated AgentController state for the conversation. It holds the current snapshot and validates updates against the `stateSchema` passed to the AgentController. Updates are serialized, and every change emits a `state_changed` event.
 
 ### `session.state.get()`
 

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

@@ -2,7 +2,7 @@
 
 # Agent class
 
-The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.
+The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses and streaming interactions. It also handles voice capabilities.
 
 ## Usage examples
 
@@ -18,7 +18,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.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 // System message object
@@ -29,7 +29,7 @@ export const agent2 = new Agent({
     role: 'system',
     content: 'You are an expert programmer',
   },
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 // Array of system messages
@@ -40,7 +40,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.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -63,7 +63,7 @@ export const agent = new Agent({
       },
     },
   },
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -102,7 +102,7 @@ For the simplest setup, pass `model` as a string in `provider/model` format. Sep
 
 Popular provider strings and credentials:
 
-- **OpenAI**: `openai/gpt-5.5` uses `OPENAI_API_KEY`.
+- **OpenAI**: `openai/gpt-5.6-sol` uses `OPENAI_API_KEY`.
 - **Anthropic**: `anthropic/claude-sonnet-4-6` uses `ANTHROPIC_API_KEY`.
 - **Google**: `google/gemini-2.5-pro` uses `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY`.
 
@@ -229,7 +229,7 @@ agent.sendMessage('Continue with the next step.', {
 })
 ```
 
-Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the message: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the message is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the message and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored message. `accepted` resolves for routing — a generation error on a `wake` run surfaces through `output.consumeStream()` — and rejects only when the message couldn't be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the message: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the message is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the message and is present only on `wake` and `deliver`. For `persist`/`discard` use `result.signal.id` to correlate the stored message. `accepted` resolves for routing (a generation error on a `wake` run surfaces through `output.consumeStream()`) and rejects only when the message couldn't be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 ### `queueMessage(message, options)`
 
@@ -272,7 +272,7 @@ Sends a signal to an active run or memory thread.
 
 **options.ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is idle.
 
-Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `action` mirrors the winning `behavior` from `ifActive`/`ifIdle`. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored signal. `accepted` resolves for routing — a generation error on a `wake` run surfaces through `output.consumeStream()` — and rejects only when the signal couldn't be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `action` mirrors the winning `behavior` from `ifActive`/`ifIdle`. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`. For `persist`/`discard` use `result.signal.id` to correlate the stored signal. `accepted` resolves for routing (a generation error on a `wake` run surfaces through `output.consumeStream()`) and rejects only when the signal couldn't be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 In serverless handlers, await `accepted` and pass the `wake` output to your platform's `waitUntil` equivalent so the winning process can drain the stream after the HTTP response returns.
 
@@ -333,11 +333,11 @@ const result = await agent.sendStateSignal(
 
 **options** (`object`): Targeting and delivery behavior for the state signal. Accepts the same options as sendSignal().
 
-Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` when Mastra accepts new state. Returns `{ skipped: true, reason: 'unchanged' }` when the same `cacheKey` and mode are already current for the state lane. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored signal. On the `wake` action, `output` is the agent stream for in-process consumption.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` when Mastra accepts new state. Returns `{ skipped: true, reason: 'unchanged' }` when the same `cacheKey` and mode are already current for the state lane. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`. For `persist`/`discard` use `result.signal.id` to correlate the stored signal. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 ### `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.
+Creates or coalesces a notification inbox record and resolves the notification delivery policy. It sends a notification signal when the decision is immediate.
 
 ```typescript
 const result = await agent.sendNotificationSignal(
@@ -387,7 +387,7 @@ const result = await agent.sendNotificationSignal(
 
 Returns `{ record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void>, accepted?: Promise<SendAgentSignalAccepted> }`. `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. `accepted` is present when a signal is emitted and resolves at decision-time, once Mastra decides what to do with it: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run, or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` on the accepted result is present only on `wake` and `deliver`. On the `wake` action, `output` is the agent stream for in-process consumption.
 
-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/long-running-agents/signals).
+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/long-running-agents/signals).
 
 Configure `notifications.deliveryPolicy` on the agent when some notifications should wait for a different dispatch window or summary rollup:
 
@@ -396,7 +396,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Help the user triage updates.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   notifications: {
     deliveryPolicy: {
       priorities: {
@@ -417,7 +417,7 @@ export const supportAgent = new Agent({
 
 ### `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.
+Subscribes to raw stream chunks for a memory thread. Use this before calling `sendMessage()`, `queueMessage()`, or `sendSignal()`. It lets you render stream output and observe signal echoes, including when a signal aborts the active run.
 
 **options** (`object`): Thread subscription target.
 
@@ -530,7 +530,7 @@ export const agent = new Agent({
   id: 'support-agent',
   name: 'support-agent',
   instructions: 'Help users with their questions.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   hooks: {
     beforeToolCall: ({ toolName, input }) => {
       console.log(`Running ${toolName}`, input)