@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.35

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

@@ -94,6 +94,89 @@ 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.
+
+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.
+
+```typescript
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+void (async () => {
+  for await (const chunk of subscription.stream) {
+    console.log(chunk)
+  }
+})()
+
+agent.sendSignal(
+  { type: 'user-message', contents: 'Use the latest customer note too.' },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+    ifIdle: {
+      streamOptions: {
+        maxSteps: 3,
+      },
+    },
+  },
+)
+```
+
+Use a custom signal type for contextual messages that should reach the model as XML-wrapped context instead of normal user input:
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'system-reminder',
+    contents: 'Continue from the previous tool result.',
+    attributes: { reminderType: 'tool-result' },
+  },
+  { resourceId: 'user-123', threadId: 'thread-abc' },
+)
+```
+
+### `sendSignal(signal, options)`
+
+Sends a signal to an active run or memory thread.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to XML context before the next model call.
+
+**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 signals.
+
+**options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted signals.
+
+**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 signal to memory.
+
+### `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.
+
+**options.resourceId** (`string`): Resource ID for the memory thread.
+
+**options.threadId** (`string`): Thread ID to subscribe to.
+
+Returns an `AgentThreadSubscription` object with these members:
+
+**stream** (`AsyncIterable<AgentChunkType>`): Raw agent stream chunks for the subscribed thread.
+
+**activeRunId** (`() => string | null`): Returns the active run ID for the thread, or \`null\` when no run is active.
+
+**abort** (`() => boolean`): Aborts the active run for the thread. Returns \`true\` when a run was aborted.
+
+**unsubscribe** (`() => void`): Stops the subscription without aborting the active run.
+
 ## Constructor parameters
 
 **id** (`string`): Unique identifier for the agent. Defaults to \`name\` if not provided.
@@ -110,6 +193,8 @@ export const agent = new Agent({
 
 **tools** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
 
+**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.
+
 **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/browser/agent-browser.md

@@ -44,22 +44,25 @@ then interact with elements using their refs (e.g., @e5).`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**excludeTools** (`BrowserToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
+
 ## Tools
 
-`AgentBrowser` provides 15 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
+`AgentBrowser` provides 16 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
 
 ### Core tools
 
-| Tool               | Description                                       |
-| ------------------ | ------------------------------------------------- |
-| `browser_goto`     | Navigate to a URL                                 |
-| `browser_snapshot` | Get accessibility tree snapshot with element refs |
-| `browser_click`    | Click an element by ref                           |
-| `browser_type`     | Type text into an element                         |
-| `browser_press`    | Press keyboard keys                               |
-| `browser_select`   | Select option from dropdown                       |
-| `browser_scroll`   | Scroll the page or element                        |
-| `browser_close`    | Close the browser                                 |
+| Tool                 | Description                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `browser_goto`       | Navigate to a URL                                                                     |
+| `browser_snapshot`   | Get accessibility tree snapshot with element refs                                     |
+| `browser_click`      | Click an element by ref                                                               |
+| `browser_type`       | Type text into an element                                                             |
+| `browser_press`      | Press keyboard keys                                                                   |
+| `browser_select`     | Select option from dropdown                                                           |
+| `browser_scroll`     | Scroll the page or element                                                            |
+| `browser_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
+| `browser_close`      | Close the browser                                                                     |
 
 ### Extended tools
 
@@ -73,6 +76,14 @@ then interact with elements using their refs (e.g., @e5).`,
 | `browser_drag`     | Drag and drop elements                          |
 | `browser_evaluate` | Execute JavaScript in the page (escape hatch)   |
 
+To exclude specific tools, pass `excludeTools` in the constructor:
+
+```typescript
+const browser = new AgentBrowser({
+  excludeTools: ['browser_screenshot'],
+})
+```
+
 ## Tool reference
 
 ### `browser_goto`
@@ -339,6 +350,21 @@ Execute JavaScript in the page context. Use as an escape hatch when other tools
 | `script`      | `string`  | JavaScript to execute (required)        |
 | `returnValue` | `boolean` | Whether to return the result (optional) |
 
+### `browser_screenshot`
+
+Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `browser_snapshot` when you only need text or structured data.
+
+```text
+// Viewport only (default)
+
+// Full scrollable page
+{ "fullPage": true }
+```
+
+| Parameter  | Type      | Description                                                                              |
+| ---------- | --------- | ---------------------------------------------------------------------------------------- |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+
 ### `browser_close`
 
 Close the browser and clean up resources.

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

@@ -61,18 +61,29 @@ Use stagehand_extract to get data from pages.`,
 
 **screencast** (`ScreencastOptions`): Configuration for streaming browser frames to Studio.
 
+**excludeTools** (`StagehandToolName[]`): Tool names to exclude from the browser toolset. Use this to disable specific tools for models that do not support certain capabilities, such as vision.
+
 ## Tools
 
-`StagehandBrowser` provides 6 AI-powered tools for browser automation:
+`StagehandBrowser` provides 7 AI-powered tools for browser automation:
+
+| Tool                   | Description                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------- |
+| `stagehand_act`        | Perform actions using natural language instructions                                   |
+| `stagehand_extract`    | Extract structured data from pages                                                    |
+| `stagehand_observe`    | Discover actionable elements on a page                                                |
+| `stagehand_navigate`   | Navigate to a URL                                                                     |
+| `stagehand_tabs`       | Manage browser tabs                                                                   |
+| `stagehand_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
+| `stagehand_close`      | Close the browser                                                                     |
 
-| Tool                 | Description                                         |
-| -------------------- | --------------------------------------------------- |
-| `stagehand_act`      | Perform actions using natural language instructions |
-| `stagehand_extract`  | Extract structured data from pages                  |
-| `stagehand_observe`  | Discover actionable elements on a page              |
-| `stagehand_navigate` | Navigate to a URL                                   |
-| `stagehand_tabs`     | Manage browser tabs                                 |
-| `stagehand_close`    | Close the browser                                   |
+To exclude specific tools, pass `excludeTools` in the constructor:
+
+```typescript
+const browser = new StagehandBrowser({
+  excludeTools: ['stagehand_screenshot'],
+})
+```
 
 ## Tool reference
 
@@ -224,6 +235,21 @@ Manage browser tabs.
 { "action": "close", "index": 1 }
 ```
 
+### `stagehand_screenshot`
+
+Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
+
+```text
+// Viewport only (default)
+
+// Full scrollable page
+{ "fullPage": true }
+```
+
+| Parameter  | Type      | Description                                                                              |
+| ---------- | --------- | ---------------------------------------------------------------------------------------- |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+
 ### `stagehand_close`
 
 Close the browser and clean up resources.

package/.docs/reference/cli/mastra.md

@@ -464,10 +464,42 @@ mastra auth tokens revoke <token-id>
 
 ## `mastra lint`
 
-The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.
+The `mastra lint` command validates the structure and code of your Mastra project.
+
+By default, `mastra lint` runs project checks against your source files and configuration. Use `--preflight` to also run bundle checks against `.mastra/output` before deployment.
+
+```bash
+mastra lint --preflight
+```
 
 It accepts [common flags](#common-flags).
 
+### Flags
+
+#### `--preflight`
+
+Runs deployment preflight checks against the built Mastra output. This builds the project before checking it unless you also pass `--skip-build`.
+
+#### `--skip-build`
+
+Skips the build step and reuses the existing `.mastra/output` directory. This flag only applies when `--preflight` is set.
+
+#### `--env-file <file>`
+
+Uses the specified environment file for preflight validation. This flag only applies when `--preflight` is set.
+
+#### `--strict`
+
+Treats warnings as errors.
+
+#### `--json`
+
+Emits machine-readable JSON output.
+
+#### `--debug`
+
+Enables debug logs.
+
 ## `mastra scorers`
 
 The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.

package/.docs/reference/client-js/agents.md

@@ -151,6 +151,95 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `sendSignal()`
+
+Send a signal to an active agent run or memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const result = await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Also consider the customer note I just added.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+console.log(result.runId)
+```
+
+Use `ifActive.behavior` and `ifIdle.behavior` to control whether Mastra delivers, persists, discards, or wakes from a signal:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Store this for later.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'persist',
+  },
+})
+```
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Start from this signal.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
+    },
+  },
+})
+```
+
+Returns `{ accepted: true, runId: string }`.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to contextual XML before the next model call.
+
+**runId** (`string`): Run ID to target directly.
+
+**resourceId** (`string`): Resource ID for the memory thread. Use with \`threadId\` for thread-targeted signals.
+
+**threadId** (`string`): Thread ID to target. Use with \`resourceId\` for thread-targeted signals.
+
+**ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`.
+
+### `subscribeToThread()`
+
+Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendSignal()`.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+await subscription.processDataStream({
+  onChunk: async chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread ID to subscribe to.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
@@ -161,7 +250,7 @@ const response = await agent.streamUntilIdle('Research solana for me', {
     thread: 'thread-1',
     resource: 'resource-1',
   },
-  maxIdleMs: 5 * 60_000,
+  maxIdleMs: 5 * 60_000, //optional
 })
 
 response.processDataStream({
@@ -173,6 +262,31 @@ response.processDataStream({
 })
 ```
 
+### `resumeStreamUntilIdle()`
+
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `resumeStream()`:
+
+```typescript
+const response = await agent.resumeStreamUntilIdle(
+  { approved: true, selectedOption: 'plan-b' },
+  {
+    memory: {
+      thread: 'thread-1',
+      resource: 'resource-1',
+    },
+    runId: 'run-123',
+    toolCallId: 'tool-call-456', // optional
+    maxIdleMs: 5 * 60_000, //optional
+  },
+)
+
+await response.processDataStream({
+  onChunk: chunk => {
+    console.log(chunk)
+  },
+})
+```
+
 The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
 
 ### `getTool()`

package/.docs/reference/client-js/responses.md

@@ -59,6 +59,8 @@ for await (const event of stream) {
 }
 ```
 
+Streaming responses can also include tool events. Tool-call streams use `response.output_item.added`, `response.function_call_arguments.delta`, `response.function_call_arguments.done`, and `response.output_item.done` events. Tool results appear as `function_call_output` items with `<toolCallId>:output` IDs.
+
 **Returns:** `Promise<ResponsesStream>`.
 
 #### `retrieve(responseId, requestContext?)`
@@ -130,6 +132,8 @@ Use [`client.conversations`](https://mastra.ai/reference/client-js/conversations
 
 If the model calls a function, that activity appears in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
 
+When `stream: true`, function calls are also emitted as Responses stream events. Read `response.function_call_arguments.delta` events for partial argument chunks and prefer `response.function_call_arguments.done` for the finalized arguments payload and tool name. Read `response.output_item.done` events for completed `function_call` and `function_call_output` items. Tool output items use `<toolCallId>:output` IDs.
+
 ## Structured output
 
 Use `text.format` when you want JSON output.

package/.docs/reference/configuration.md

@@ -175,20 +175,20 @@ Custom ID generator function for creating unique identifiers. Mastra passes opti
 > **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users won't need to configure this option.
 
 ```typescript
+import { v4 as uuid } from '@lukeed/uuid'
 import { Mastra } from '@mastra/core'
-import { nanoid } from 'nanoid'
 
 export const mastra = new Mastra({
   idGenerator: context => {
     if (context?.idType === 'message' && context?.threadId) {
-      return `msg-${context.threadId}-${nanoid(8)}`
+      return `msg-${context.threadId}-${uuid()}`
     }
 
     if (context?.idType === 'run' && context?.source && context?.entityId) {
-      return `${context.source}-run-${context.entityId}-${nanoid(6)}`
+      return `${context.source}-run-${context.entityId}-${uuid()}`
     }
 
-    return nanoid()
+    return uuid()
   },
 })
 ```
@@ -277,7 +277,7 @@ Visit the [Observability documentation](https://mastra.ai/docs/observability/ove
 ```typescript
 import { Mastra } from '@mastra/core'
 import { LibSQLStore } from '@mastra/libsql'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
@@ -288,7 +288,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),

package/.docs/reference/editor/tool-provider.md

@@ -14,7 +14,7 @@ Tool providers implement these methods:
 
 **getToolSchema(slug)** (`(slug: string) => Promise<JSONSchema>`): Returns the JSON schema for a specific tool identified by its slug.
 
-**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. The options object can include userId for per-user authentication.
+**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. Built-in providers use resourceId from request context for per-user authentication.
 
 ***
 
@@ -47,7 +47,7 @@ Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MES
 
 ### Authentication
 
-Tool execution is scoped to a `userId` passed through request context. Each user authenticates with the integration separately through Composio's auth flow.
+Tool execution is scoped to the `resourceId` passed through request context. The provider maps that value to the user identity required by Composio's auth flow.
 
 ***
 
@@ -82,4 +82,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-Like Composio, tool execution requires a `userId` for per-user authorization through Arcade's auth flow.
+Like Composio, tool execution uses `resourceId` from request context for per-user authorization. The provider maps that value to the user identity required by Arcade's auth flow.

package/.docs/reference/harness/harness-class.md

@@ -98,7 +98,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
 
-**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_check\`, and \`subagent\`.
+**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
 
 **heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
 
@@ -162,6 +162,17 @@ Return the current `HarnessDisplayState` snapshot for UI rendering.
 const displayState = harness.getDisplayState()
 ```
 
+#### `restoreDisplayTasks(tasks)`
+
+Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
+
+If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+
+```typescript
+await harness.setState({ tasks: replayedTasks })
+harness.restoreDisplayTasks(replayedTasks)
+```
+
 #### `setState(updates)`
 
 Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.
@@ -831,13 +842,15 @@ The harness emits events through registered listeners. The following table lists
 
 The harness 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 update a structured task list for tracking progress.                                                                                                                                       |
-| `task_check`  | Check the completion status of the current task list.                                                                                                                                                |
-| `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/index.md

@@ -170,6 +170,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
 - [ProviderHistoryCompat](https://mastra.ai/reference/processors/provider-history-compat)
 - [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
+- [ResponseCache](https://mastra.ai/reference/processors/response-cache)
 - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
@@ -198,6 +199,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [Overview](https://mastra.ai/reference/storage/overview)
+- [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
 - [ClickHouse Storage](https://mastra.ai/reference/storage/clickhouse)
 - [Cloudflare D1 Storage](https://mastra.ai/reference/storage/cloudflare-d1)
 - [Cloudflare KV Storage](https://mastra.ai/reference/storage/cloudflare)
@@ -222,6 +224,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.stream()](https://mastra.ai/reference/streaming/workflows/stream)
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
+- [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
@@ -256,6 +259,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Events](https://mastra.ai/reference/voice/voice.events)
 - [Google](https://mastra.ai/reference/voice/google)
 - [Google Gemini Live](https://mastra.ai/reference/voice/google-gemini-live)
+- [Inworld](https://mastra.ai/reference/voice/inworld)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)
@@ -278,6 +282,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
+- [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.branch()](https://mastra.ai/reference/workflows/workflow-methods/branch)
 - [.commit()](https://mastra.ai/reference/workflows/workflow-methods/commit)
 - [.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/.docs/reference/memory/observational-memory.md

@@ -36,7 +36,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+**activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
+
+**activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use \`reflection.activateOnProviderChange\` to opt reflections into provider-change activation. (Default: `false`)
 
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
@@ -66,6 +68,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
 
+**observation.activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
+
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level \`activateOnProviderChange\` value is used for observations.
+
 **observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to \`0\` to omit previous observations entirely, or \`false\` to disable truncation explicitly.
@@ -86,6 +92,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
+**reflection.activateAfterIdle** (`number | string | false`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
+
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level \`activateOnProviderChange\`; set this explicitly to opt reflections into provider-change activation.
+
 **reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled.
 
 ### Token estimate metadata cache