@mastra/mcp-docs-server 1.1.35-alpha.11 → 1.1.35-alpha.15

package/.docs/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -1,6 +1,6 @@
-# Advanced Configuration of Semantic Recall
+# Advanced configuration of semantic recall
 
-We can configure semantic recall in more detail by setting options for the `semanticRecall` option:
+Configure semantic recall with the `semanticRecall` option:
 
 ```typescript
 const memory = new Memory({
@@ -19,11 +19,55 @@ const memory = new Memory({
         before: 2,
         after: 1,
       },
+      scope: 'resource', // Search all threads for this resource
+      filter: { projectId: { $eq: 'project-a' } },
     },
   },
 })
 ```
 
-The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information. The default value is `4`.
+The `topK` parameter controls how many similar messages Mastra retrieves. A higher value retrieves more messages, which can help with complex topics but may include less relevant information. The default value is `4`.
 
-The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.
+The `messageRange` parameter controls how much context Mastra includes with each match. Messages before and after the match help the agent understand the matched message.
+
+The `scope` parameter controls whether Mastra searches the current thread (`'thread'`) or all threads owned by a resource (`'resource'`). Use `scope: 'resource'` to let the agent recall information from past conversations for the same resource.
+
+The `filter` parameter restricts semantic recall results to messages with matching thread metadata, such as a project ID or category.
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```

package/.docs/docs/agents/using-tools.md

@@ -224,6 +224,14 @@ export const weatherTool = createTool({
 })
 ```
 
+## Transform tool payloads for UI and transcripts
+
+Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.
+
+If a transform is configured and it fails, Mastra does not fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
+
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
+
 ## Control tool selection
 
 Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.

package/.docs/docs/editor/tools.md

@@ -73,7 +73,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    })
    ```
 
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to a `userId` passed through request context for per-user authentication.
+   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to the `resourceId` passed through request context for per-user authentication.
 
 ### Arcade
 

package/.docs/docs/memory/semantic-recall.md

@@ -121,26 +121,88 @@ Each vector store page below includes installation instructions, configuration p
 
 ## Recall configuration
 
-The three main parameters that control semantic recall behavior are:
+The following options control semantic recall behavior:
 
-1. **topK**: How many semantically similar messages to retrieve
-2. **messageRange**: How much surrounding context to include with each match
-3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
+1. **topK**: The number of similar messages to retrieve
+2. **messageRange**: The surrounding messages to include with each match
+3. **scope**: Whether to search the current thread or all threads for a resource
+4. **filter**: Metadata criteria that restrict search results
 
 ```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
       semanticRecall: {
-        topK: 3, // Retrieve 3 most similar messages
+        topK: 3, // Retrieve 3 similar messages
         messageRange: 2, // Include 2 messages before and after each match
-        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+        scope: 'resource', // Search all threads for this resource
+        filter: { projectId: { $eq: 'project-a' } },
       },
     },
   }),
 })
 ```
 
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+
+### Metadata filtering
+
+The `filter` option restricts semantic recall results to messages with matching thread metadata.
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        scope: 'resource',
+        filter: {
+          projectId: { $eq: 'project-a' },
+          category: { $in: ['work', 'personal'] },
+        },
+      },
+    },
+  }),
+})
+```
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.

package/.docs/docs/observability/tracing/exporters/default.md

@@ -174,7 +174,42 @@ The DefaultExporter includes robust error handling for production use:
 - **Persistent Failures**: Drop batch after 4 failed attempts
 - **Buffer Overflow**: Prevent memory issues during storage outages
 
-### Configuration Examples
+## Dropped observability events
+
+`DefaultExporter` emits structured drop events when it cannot persist observability data. Register an exporter or bridge with `onDroppedEvent` to forward these drops to alerting or monitoring.
+
+There are two drop reasons:
+
+- `unsupported-storage`: The storage provider does not implement the signal type.
+- `retry-exhausted`: The exporter retried a batch up to `maxRetries` times and then dropped it.
+
+The following example demonstrates forwarding drop details to a monitoring endpoint:
+
+```typescript
+import { BaseExporter } from '@mastra/observability'
+import type { ObservabilityDropEvent, TracingEvent } from '@mastra/core/observability'
+
+class DropAlertExporter extends BaseExporter {
+  name = 'drop-alerts'
+
+  async onDroppedEvent(event: ObservabilityDropEvent) {
+    await fetch('https://monitoring.example.com/observability-drops', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        count: event.count,
+        signal: event.signal,
+        reason: event.reason,
+        exporterName: event.exporterName,
+      }),
+    })
+  }
+
+  protected async _exportTracingEvent(_event: TracingEvent) {}
+}
+```
+
+## Configuration examples
 
 ```typescript
 // Zero config - recommended for most users

package/.docs/docs/workflows/suspend-and-resume.md

@@ -188,6 +188,32 @@ The `suspended` array contains the IDs of any suspended workflows and steps from
 ['nested-workflow', 'step-1']
 ```
 
+## Recovering suspended runs
+
+Use `workflow.getWorkflowRunById()` with `createWorkflowStateReader()` when your application needs to recover a suspended run from storage. The reader exposes suspended steps, resume labels, step payloads, and step outputs without reading the raw snapshot shape.
+
+```typescript
+import { createWorkflowStateReader } from '@mastra/core/workflows'
+
+const workflow = mastra.getWorkflow('testWorkflow')
+const state = await workflow.getWorkflowRunById('run-123')
+
+if (state?.status === 'suspended') {
+  const reader = createWorkflowStateReader(state)
+  const suspendedStep = reader.getSuspendedStep()
+  const approvalLabel = reader.getResumeLabel('approve')
+  const run = await workflow.createRun({ runId: state.runId })
+
+  await run.resume({
+    step: approvalLabel?.stepId ?? suspendedStep?.path,
+    resumeData: { approved: true },
+    forEachIndex: approvalLabel?.foreachIndex,
+  })
+}
+```
+
+For nested workflows, `suspendedStep.path` contains the resume path. For `foreach` suspensions, matching resume labels include `foreachIndex` when the label points to a specific iteration.
+
 ## Sleep
 
 Sleep methods can be used to pause execution at the workflow level, which sets the status to `waiting`. By comparison, `suspend()` pauses execution within a specific step and sets the status to `suspended`.
@@ -202,4 +228,5 @@ Sleep methods can be used to pause execution at the workflow level, which sets t
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
 - [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)
 - [Snapshots](https://mastra.ai/docs/workflows/snapshots)
-- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Workflow state reader](https://mastra.ai/reference/workflows/workflow-state-reader)

package/.docs/models/gateways/openrouter.md

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 188 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 189 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -195,6 +195,7 @@ ANTHROPIC_API_KEY=ant-...
 | `sourceful/riverflow-v2-max-preview`                            |
 | `sourceful/riverflow-v2-standard-preview`                       |
 | `stepfun/step-3.5-flash`                                        |
+| `tencent/hy3-preview`                                           |
 | `x-ai/grok-3`                                                   |
 | `x-ai/grok-3-beta`                                              |
 | `x-ai/grok-3-mini`                                              |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3879 models from 108 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3891 models from 108 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/digitalocean.md

@@ -1,6 +1,6 @@
 # ![DigitalOcean logo](https://models.dev/logos/digitalocean.svg)DigitalOcean
 
-Access 64 DigitalOcean models through Mastra's model router. Authentication is handled automatically using the `DIGITALOCEAN_ACCESS_TOKEN` environment variable.
+Access 71 DigitalOcean models through Mastra's model router. Authentication is handled automatically using the `DIGITALOCEAN_ACCESS_TOKEN` environment variable.
 
 Learn more in the [DigitalOcean documentation](https://docs.digitalocean.com/products/gradient-ai-platform/details/models/).
 
@@ -37,6 +37,7 @@ for await (const chunk of stream) {
 | `digitalocean/alibaba-qwen3-32b`                     | 131K    |       |           |       |       |       | $0.25      | $0.55       |
 | `digitalocean/all-mini-lm-l6-v2`                     | 256     |       |           |       |       |       | $0.01      | —           |
 | `digitalocean/anthropic-claude-4.1-opus`             | 200K    |       |           |       |       |       | $15        | $75         |
+| `digitalocean/anthropic-claude-4.5-haiku`            | 200K    |       |           |       |       |       | $1         | $5          |
 | `digitalocean/anthropic-claude-4.5-sonnet`           | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `digitalocean/anthropic-claude-4.6-sonnet`           | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `digitalocean/anthropic-claude-haiku-4.5`            | 200K    |       |           |       |       |       | $1         | $5          |
@@ -50,6 +51,7 @@ for await (const chunk of stream) {
 | `digitalocean/bge-reranker-v2-m3`                    | 8K      |       |           |       |       |       | $0.01      | —           |
 | `digitalocean/deepseek-3.2`                          | 128K    |       |           |       |       |       | $0.50      | $2          |
 | `digitalocean/deepseek-r1-distill-llama-70b`         | 131K    |       |           |       |       |       | $0.99      | $0.99       |
+| `digitalocean/deepseek-v3`                           | 164K    |       |           |       |       |       | —          | —           |
 | `digitalocean/deepseek-v4-pro`                       | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `digitalocean/e5-large-v2`                           | 512     |       |           |       |       |       | $0.02      | —           |
 | `digitalocean/fal-ai/elevenlabs/tts/multilingual-v2` | —       |       |           |       |       |       | —          | —           |
@@ -62,11 +64,14 @@ for await (const chunk of stream) {
 | `digitalocean/kimi-k2.5`                             | 262K    |       |           |       |       |       | $0.50      | $3          |
 | `digitalocean/kimi-k2.6`                             | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `digitalocean/llama-4-maverick`                      | 1.0M    |       |           |       |       |       | $0.25      | $0.87       |
-| `digitalocean/llama-guard-4-12b`                     | 128K    |       |           |       |       |       | —          | —           |
+| `digitalocean/llama3-8b-instruct`                    | 131K    |       |           |       |       |       | $0.20      | $0.20       |
 | `digitalocean/llama3.3-70b-instruct`                 | 128K    |       |           |       |       |       | $0.65      | $0.65       |
 | `digitalocean/minimax-m2.5`                          | 205K    |       |           |       |       |       | $0.30      | $1          |
+| `digitalocean/ministral-3-8b-instruct-2512`          | 262K    |       |           |       |       |       | —          | —           |
 | `digitalocean/mistral-3-14B`                         | 262K    |       |           |       |       |       | $0.20      | $0.20       |
+| `digitalocean/mistral-7b-instruct-v0.3`              | 33K     |       |           |       |       |       | —          | —           |
 | `digitalocean/multi-qa-mpnet-base-dot-v1`            | 512     |       |           |       |       |       | $0.01      | —           |
+| `digitalocean/nemotron-3-nano-30b`                   | 262K    |       |           |       |       |       | —          | —           |
 | `digitalocean/nemotron-3-nano-omni`                  | 66K     |       |           |       |       |       | $0.50      | $0.90       |
 | `digitalocean/nemotron-nano-12b-v2-vl`               | 128K    |       |           |       |       |       | $0.20      | $0.60       |
 | `digitalocean/nvidia-nemotron-3-super-120b`          | 256K    |       |           |       |       |       | $0.30      | $0.65       |
@@ -87,11 +92,13 @@ for await (const chunk of stream) {
 | `digitalocean/openai-gpt-5.5`                        | 1.0M    |       |           |       |       |       | $5         | $30         |
 | `digitalocean/openai-gpt-image-1`                    | —       |       |           |       |       |       | $5         | $40         |
 | `digitalocean/openai-gpt-image-1.5`                  | —       |       |           |       |       |       | $5         | $10         |
+| `digitalocean/openai-gpt-image-2`                    | —       |       |           |       |       |       | —          | —           |
 | `digitalocean/openai-gpt-oss-120b`                   | 131K    |       |           |       |       |       | $0.10      | $0.70       |
 | `digitalocean/openai-gpt-oss-20b`                    | 131K    |       |           |       |       |       | $0.05      | $0.45       |
 | `digitalocean/openai-o1`                             | 200K    |       |           |       |       |       | $15        | $60         |
 | `digitalocean/openai-o3`                             | 200K    |       |           |       |       |       | $2         | $8          |
 | `digitalocean/openai-o3-mini`                        | 200K    |       |           |       |       |       | $1         | $4          |
+| `digitalocean/qwen-2.5-14b-instruct`                 | 131K    |       |           |       |       |       | —          | —           |
 | `digitalocean/qwen3-coder-flash`                     | 262K    |       |           |       |       |       | $0.45      | $2          |
 | `digitalocean/qwen3-embedding-0.6b`                  | 8K      |       |           |       |       |       | $0.04      | —           |
 | `digitalocean/qwen3-tts-voicedesign`                 | 33K     |       |           |       |       |       | —          | —           |

package/.docs/models/providers/google.md

@@ -1,6 +1,6 @@
 # ![Google logo](https://models.dev/logos/google.svg)Google
 
-Access 37 Google models through Mastra's model router. Authentication is handled automatically using the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable.
+Access 38 Google models through Mastra's model router. Authentication is handled automatically using the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable.
 
 Learn more in the [Google documentation](https://ai.google.dev/gemini-api/docs/pricing).
 
@@ -54,6 +54,7 @@ for await (const chunk of stream) {
 | `google/gemini-3-flash-preview`                     | 1.0M    |       |           |       |       |       | $0.50      | $3          |
 | `google/gemini-3-pro-preview`                       | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `google/gemini-3.1-flash-image-preview`             | 131K    |       |           |       |       |       | $0.25      | $60         |
+| `google/gemini-3.1-flash-lite`                      | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `google/gemini-3.1-flash-lite-preview`              | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `google/gemini-3.1-pro-preview`                     | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `google/gemini-3.1-pro-preview-customtools`         | 1.0M    |       |           |       |       |       | $2         | $12         |

package/.docs/models/providers/poe.md

@@ -1,6 +1,6 @@
 # ![Poe logo](https://models.dev/logos/poe.svg)Poe
 
-Access 121 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
+Access 124 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
 
 Learn more in the [Poe documentation](https://creator.poe.com/docs/external-applications/openai-compatible-api).
 
@@ -51,6 +51,8 @@ for await (const chunk of stream) {
 | `poe/elevenlabs/elevenlabs-music`      | 2K      |       |           |       |       |       | —          | —           |
 | `poe/elevenlabs/elevenlabs-v2.5-turbo` | 128K    |       |           |       |       |       | —          | —           |
 | `poe/elevenlabs/elevenlabs-v3`         | 128K    |       |           |       |       |       | —          | —           |
+| `poe/empiriolabs/deepseek-v4-flash-el` | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `poe/empiriolabs/deepseek-v4-pro-el`   | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `poe/fireworks-ai/kimi-k2.5-fw`        | 262K    |       |           |       |       |       | —          | —           |
 | `poe/google/gemini-2.0-flash`          | 990K    |       |           |       |       |       | $0.10      | $0.42       |
 | `poe/google/gemini-2.0-flash-lite`     | 990K    |       |           |       |       |       | $0.05      | $0.21       |
@@ -87,6 +89,7 @@ for await (const chunk of stream) {
 | `poe/novita/glm-5`                     | 205K    |       |           |       |       |       | $1         | $3          |
 | `poe/novita/kimi-k2-thinking`          | 256K    |       |           |       |       |       | —          | —           |
 | `poe/novita/kimi-k2.5`                 | 128K    |       |           |       |       |       | $0.60      | $3          |
+| `poe/novita/kimi-k2.6`                 | 262K    |       |           |       |       |       | $0.96      | $4          |
 | `poe/novita/minimax-m2.1`              | 205K    |       |           |       |       |       | —          | —           |
 | `poe/openai/dall-e-3`                  | 800     |       |           |       |       |       | —          | —           |
 | `poe/openai/gpt-3.5-turbo`             | 16K     |       |           |       |       |       | $0.45      | $1          |

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

@@ -110,6 +110,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/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()
   },
 })
 ```

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

@@ -278,6 +278,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/observability/tracing/configuration.md

@@ -7,6 +7,7 @@ interface ObservabilityRegistryConfig {
   default?: { enabled?: boolean }
   configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
   configSelector?: ConfigSelector
+  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
 }
 ```
 
@@ -16,6 +17,8 @@ interface ObservabilityRegistryConfig {
 
 **configSelector** (`ConfigSelector`): Runtime configuration selector function
 
+**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): Controls whether a \[SensitiveDataFilter]\(/reference/observability/tracing/processors/sensitive-data-filter) is auto-applied to every configured instance. Defaults to \`true\`. Pass \`false\` to opt out, or pass a \`SensitiveDataFilterOptions\` object to customize fields, redaction token, or redaction style. If a config already includes a \`SensitiveDataFilter\` in \`spanOutputProcessors\`, it is not duplicated. Pre-instantiated instances are not modified.
+
 ## `ObservabilityInstanceConfig`
 
 ```typescript

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -128,6 +128,8 @@ Failed flushes are retried with exponential backoff:
 - Maximum attempts: `maxRetries`
 - Batch is dropped after all retries fail
 
+When storage does not support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
+
 ### Out-of-Order Handling
 
 For `batch-with-updates` strategy:

package/.docs/reference/observability/tracing/interfaces.md

@@ -141,10 +141,18 @@ interface ObservabilityExporter {
   /** Handle feedback events */
   onFeedbackEvent?(event: FeedbackEvent): void | Promise<void>
 
+  /** Handle exporter pipeline droppedEvent */
+  onDroppedEvent?(event: ObservabilityDropEvent): void | Promise<void>
+
   /** Export tracing events */
   exportTracingEvent(event: TracingEvent): Promise<void>
 
-  /** Add score to a trace (optional) */
+  /**
+   * @deprecated Implement `onScoreEvent` instead. Eval scores now flow through the
+   * unified observability bus as `ScoreEvent`s. This method is preserved on the
+   * interface for backwards compatibility with existing exporters; new exporters
+   * should not implement it.
+   */
   addScoreToTrace?({
     traceId,
     spanId,
@@ -171,6 +179,33 @@ interface ObservabilityExporter {
 
 Event callback payloads use observability event bus envelopes: `TracingEvent` carries span lifecycle events with `exportedSpan`, `LogEvent` wraps `ExportedLog` in `log`, `MetricEvent` wraps `ExportedMetric` in `metric`, `ScoreEvent` wraps `ExportedScore` in `score`, and `FeedbackEvent` wraps `ExportedFeedback` in `feedback`. For Cloud exporter behavior for these callbacks, see [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter).
 
+### `ObservabilityDropEvent`
+
+Structured event emitted when the exporter pipeline drops observability events.
+
+```typescript
+type ObservabilityDropSignal = 'tracing' | 'log' | 'metric' | 'score' | 'feedback'
+
+type ObservabilityDropReason = 'unsupported-storage' | 'retry-exhausted'
+
+interface ObservabilityDropEvent {
+  type: 'drop'
+  signal: ObservabilityDropSignal
+  reason: ObservabilityDropReason
+  count: number
+  timestamp: Date
+  exporterName: string
+  storageName?: string
+  error?: {
+    id?: string
+    domain?: string
+    message: string
+  }
+}
+```
+
+Use `onDroppedEvent` on a custom exporter or bridge to forward these events to external metrics or alerting systems.
+
 ### `SpanOutputProcessor`
 
 Interface for span output processors.

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -2,6 +2,28 @@
 
 A SpanOutputProcessor that redacts sensitive information from span fields.
 
+## Auto-applied by default
+
+`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You do not need to add it manually unless you want to customize its options.
+
+To opt out or customize the auto-applied filter, use the `sensitiveDataFilter` option on the [`Observability` registry config](https://mastra.ai/reference/observability/tracing/configuration):
+
+```typescript
+import { Observability } from '@mastra/observability'
+
+new Observability({
+  configs: {
+    /* ... */
+  },
+  // disable the auto-applied filter
+  sensitiveDataFilter: false,
+  // or customize it
+  // sensitiveDataFilter: { sensitiveFields: ['mySecret'], redactionStyle: 'partial' },
+})
+```
+
+If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values are not modified — add a `SensitiveDataFilter` to their processors yourself if needed.
+
 ## Constructor
 
 ```typescript

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

@@ -173,6 +173,50 @@ The tool still returns the full `execute` result to your application, while the
 - `type: 'json'`
 - `type: 'content'` with parts like `text`, `image-url`, `image-data`, `file-url`, `file-data`, `file-id`, `image-file-id`, or `custom`
 
+## Example with `transform`
+
+Use `transform` when the tool should keep raw inputs or outputs for runtime behavior, but display streams or transcript messages should receive a smaller or safer shape.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const customerTool = createTool({
+  id: 'lookup-customer',
+  description: 'Looks up a customer',
+  inputSchema: z.object({
+    customerId: z.string(),
+    internalPath: z.string(),
+  }),
+  outputSchema: z.object({
+    displayName: z.string(),
+    apiKey: z.string(),
+    debugScore: z.number(),
+  }),
+  execute: async () => {
+    return {
+      displayName: 'Acme',
+      apiKey: 'secret-value',
+      debugScore: 0.97,
+    }
+  },
+  transform: {
+    display: {
+      input: ({ input }) => ({ customerId: input?.customerId }),
+      output: ({ output }) => ({ displayName: output?.displayName }),
+      error: () => ({ message: 'Customer lookup failed' }),
+    },
+    transcript: {
+      input: ({ input }) => ({ customerId: input?.customerId }),
+      output: ({ output }) => ({ displayName: output?.displayName }),
+      error: () => ({ message: 'Customer lookup failed' }),
+    },
+  },
+})
+```
+
+The tool still receives the raw `inputSchema` value and returns the raw `execute` result. Mastra applies `display` transforms to streamed UI payloads and `transcript` transforms to user-visible transcript messages.
+
 ## Example with MCP annotations
 
 When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
@@ -224,6 +268,8 @@ export const weatherTool = createTool({
 
 **toModelOutput** (`(output: TSchemaOut) => unknown`): Optional function that transforms the tool's \`execute\` output before it is sent back to the model. Use this to return \`text\`, \`json\`, or \`content\`-shaped outputs (including multimodal parts like images/files) to the model while still keeping the full raw output in your application code.
 
+**transform** (`ToolPayloadTransform`): Optional target-aware transform for tool payloads before they leave runtime for display streams or user-visible transcript messages. Configure \`display\` and \`transcript\` transforms for phases such as \`input\`, \`inputDelta\`, \`output\`, \`error\`, \`approval\`, \`suspend\`, and \`resume\`.
+
 **suspendSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the structure of the payload passed to \`suspend()\`. This payload is returned to the client when the tool suspends execution.
 
 **resumeSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected structure of \`resumeData\` when the tool is resumed. Used by the agent to extract data from user messages when \`autoResumeSuspendedTools\` is enabled.

package/.docs/reference/workflows/workflow-state-reader.md

@@ -0,0 +1,113 @@
+# Workflow state reader
+
+Workflow state reader helpers inspect the public `WorkflowState` returned by `workflow.getWorkflowRunById()`. Use them to recover suspended runs, inspect resume labels, and read step payloads or outputs without parsing raw workflow snapshots.
+
+## Usage example
+
+```typescript
+import { createWorkflowStateReader } from '@mastra/core/workflows'
+
+const state = await workflow.getWorkflowRunById('run-123')
+
+if (state) {
+  const reader = createWorkflowStateReader(state)
+  const suspendedStep = reader.getSuspendedStep()
+  const labels = reader.getResumeLabels()
+
+  console.log(reader.getStatus())
+  console.log(reader.getStepOutput('extract-data'))
+  console.log(suspendedStep?.path)
+  console.log(labels.approve)
+}
+```
+
+## Functions
+
+### `createWorkflowStateReader(state)`
+
+Creates a reader object with methods bound to one `WorkflowState`.
+
+```typescript
+const reader = createWorkflowStateReader(state)
+const suspendedStep = reader.getSuspendedStep()
+```
+
+### `getWorkflowStepOutput(state, stepId)`
+
+Returns the output for a step ID, including nested workflow dot paths such as `parent.child`. For `foreach` steps, returns one entry per iteration; suspended iterations can have `undefined` output entries.
+
+```typescript
+const output = getWorkflowStepOutput(state, 'extract-data')
+```
+
+### `getWorkflowStepPayload(state, stepId)`
+
+Returns the payload that was passed to a step. For `foreach` steps, returns one entry per iteration.
+
+```typescript
+const payload = getWorkflowStepPayload(state, 'extract-data')
+```
+
+### `getWorkflowSuspendedStep(state)`
+
+Returns the first suspended step from the workflow state. When multiple steps are suspended, ordering follows the order stored in `suspendedPaths`.
+
+```typescript
+const suspendedStep = getWorkflowSuspendedStep(state)
+```
+
+### `getWorkflowSuspendedSteps(state)`
+
+Returns all suspended steps from the workflow state. Each result includes the top-level step ID, resume path, execution path, suspend payload, suspend output, and matching resume labels.
+
+```typescript
+const suspendedSteps = getWorkflowSuspendedSteps(state)
+```
+
+### `getWorkflowResumeLabel(state, label)`
+
+Returns a resume label by name.
+
+```typescript
+const label = getWorkflowResumeLabel(state, 'approve')
+```
+
+### `getWorkflowResumeLabels(state)`
+
+Returns all resume labels from the workflow state.
+
+```typescript
+const labels = getWorkflowResumeLabels(state)
+```
+
+## Reader methods
+
+`createWorkflowStateReader(state)` returns the following methods:
+
+**getStatus** (`() => WorkflowRunStatus`): Returns the workflow run status.
+
+**getResult** (`() => WorkflowState["result"]`): Returns the terminal workflow result when it exists.
+
+**getError** (`() => WorkflowState["error"]`): Returns the terminal workflow error when it exists.
+
+**getStepOutput** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the output for a step ID or nested workflow dot path.
+
+**getStepPayload** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the payload for a step ID or nested workflow dot path.
+
+**getSuspendedStep** (`() => { stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> } | undefined`): Returns the first suspended step.
+
+**getSuspendedSteps** (`() => Array<{ stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> }>`): Returns all suspended steps.
+
+**getResumeLabel** (`(label: string) => { stepId: string; foreachIndex?: number } | undefined`): Returns a resume label by name.
+
+**getResumeLabels** (`() => Record<string, { stepId: string; foreachIndex?: number }>`): Returns all resume labels.
+
+## Notes
+
+`requestContext` and `tracingContext` are only returned by `workflow.getWorkflowRunById()` when explicitly requested with `fields`.
+
+## Related
+
+- [Suspend & resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
+- [Workflow class](https://mastra.ai/reference/workflows/workflow)

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.35-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`6742347`](https://github.com/mastra-ai/mastra/commit/6742347d71955d7639adc9ddf6ff8282de7ee3ba), [`7b0ad1f`](https://github.com/mastra-ai/mastra/commit/7b0ad1f5c53dc118c6da12ae82ae2587037dc2b8), [`62666c3`](https://github.com/mastra-ai/mastra/commit/62666c367eaeac3941ead454b1d38810cc855721), [`4af2160`](https://github.com/mastra-ai/mastra/commit/4af2160322f4718cac421930cce85641e9512389), [`136c959`](https://github.com/mastra-ai/mastra/commit/136c9592fb0eeb0cd212f28629d8a29b7557a2fc), [`4df7cc7`](https://github.com/mastra-ai/mastra/commit/4df7cc79342fd065fe7fdeef93c094db14b12bcd), [`aca3121`](https://github.com/mastra-ai/mastra/commit/aca31211233dac25459f140ea4fcfb3a5af64c18), [`9cdf38e`](https://github.com/mastra-ai/mastra/commit/9cdf38e58506e1109c8b38f97cd7770978a4218e), [`990851e`](https://github.com/mastra-ai/mastra/commit/990851edcb0e30be5c2c18b6532f1a876cc2d335), [`6068a6c`](https://github.com/mastra-ai/mastra/commit/6068a6c42950fad3ebfc92346417896ba60803d2), [`00106be`](https://github.com/mastra-ai/mastra/commit/00106bede59b81e5b0e9cd6aad8d3b5dbc336387), [`e2a079c`](https://github.com/mastra-ai/mastra/commit/e2a079cc3755b1895f7bd5dc36e9be81b11c7c22), [`534a456`](https://github.com/mastra-ai/mastra/commit/534a456a25e4df1e5407e7e632f4cb3b1fa14f9d), [`36bae07`](https://github.com/mastra-ai/mastra/commit/36bae07c0e70b1b3006f2fd20830e8883dcbd066)]:
+  - @mastra/core@1.33.0-alpha.7
+
+## 1.1.35-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`b560d6f`](https://github.com/mastra-ai/mastra/commit/b560d6f88b9b904b15c10f75c949eb145bc27684), [`36b3bbf`](https://github.com/mastra-ai/mastra/commit/36b3bbf5a8d59f7e23d47e29340e76c681b4929c), [`b275631`](https://github.com/mastra-ai/mastra/commit/b275631dc10541a482b2e2d4a3e3cfa843bd5fa1)]:
+  - @mastra/core@1.33.0-alpha.6
+
 ## 1.1.35-alpha.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.35-alpha.11",
+  "version": "1.1.35-alpha.15",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
     "@mastra/mcp": "^1.7.0",
-    "@mastra/core": "1.33.0-alpha.5"
+    "@mastra/core": "1.33.0-alpha.7"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -48,7 +48,7 @@
     "vitest": "4.1.5",
     "@internal/lint": "0.0.92",
     "@internal/types-builder": "0.0.67",
-    "@mastra/core": "1.33.0-alpha.5"
+    "@mastra/core": "1.33.0-alpha.7"
   },
   "homepage": "https://mastra.ai",
   "repository": {