@mastra/mcp-docs-server 1.1.35-alpha.13 → 1.1.35-alpha.17

package/.docs/models/providers/opencode.md

@@ -1,6 +1,6 @@
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 39 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 38 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -64,7 +64,6 @@ for await (const chunk of stream) {
 | `opencode/gpt-5.4-pro`           | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `opencode/gpt-5.5`               | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `opencode/gpt-5.5-pro`           | 1.1M    |       |           |       |       |       | $30        | $180        |
-| `opencode/hy3-preview-free`      | 256K    |       |           |       |       |       | —          | —           |
 | `opencode/kimi-k2.5`             | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `opencode/kimi-k2.6`             | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `opencode/minimax-m2.5`          | 205K    |       |           |       |       |       | $0.30      | $1          |

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/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)
@@ -278,6 +279,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

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -77,7 +77,7 @@ Flushes pending data and shuts down the client.
 ```typescript
 import { ArizeExporter } from '@mastra/arize'
 
-// For Phoenix: Set PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
+// For Phoenix: Set PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
 // For Arize AX: Set ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME
 const exporter = new ArizeExporter()
 ```

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/processors/response-cache.md

@@ -0,0 +1,114 @@
+# ResponseCache
+
+`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).
+
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
+
+There is no agent-level option for response caching; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+const agent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })],
+})
+
+// First call hits the LLM and writes to the cache.
+await agent.generate('What is the capital of France?')
+
+// Second identical call replays the cached response.
+await agent.generate('What is the capital of France?')
+
+// Force a fresh call but still update the cache.
+await agent.generate('What is the capital of France?', {
+  requestContext: ResponseCache.context({ bust: true }),
+})
+```
+
+See [Response caching](https://mastra.ai/docs/agents/response-caching) for the conceptual overview, scoping rules, and recommended deployment patterns.
+
+## Constructor parameters
+
+**cache** (`MastraServerCache`): The cache backend. Required. Pass any \`MastraServerCache\` implementation — \`InMemoryServerCache\` for local development, \`RedisCache\` from \`@mastra/redis\` for production, or your own subclass for a custom backend.
+
+**ttl** (`number`): Time-to-live (seconds) for entries written by this processor. Defaults to 300 seconds (5 minutes), matching OpenRouter's reference implementation. (Default: `300`)
+
+**scope** (`string | null`): Tenant scope appended to the cache key. \`null\` opts out of scoping. When omitted, the processor falls back to the resource id resolved from the request context (\`MASTRA\_RESOURCE\_ID\_KEY\`) for automatic per-user isolation.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Override the auto-derived cache key. Pass a string to pin a key, or a function that receives \`{ agentId, scope, model, prompt, stepNumber }\` and returns a key. If the function throws, the processor falls back to the deterministic hash so the call still benefits from caching.
+
+**bust** (`boolean`): Force a cache miss on every call: skip the read but still write on completion. Useful for explicit refresh paths. (Default: `false`)
+
+**agentId** (`string`): Logical id used in the cache key namespace. Defaults to \`'mastra-response-cache'\`. Set this to the owning agent's id when you want cache entries scoped per-agent. (Default: `'mastra-response-cache'`)
+
+## Static helpers
+
+`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail — prefer them over reading/writing the raw key.
+
+### `ResponseCache.context(options)`
+
+Build a fresh `RequestContext` preloaded with per-call response cache overrides.
+
+```typescript
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom', bust: true }),
+})
+```
+
+### `ResponseCache.applyContext(requestContext, options)`
+
+Merge per-call response cache overrides into an existing `RequestContext`. Returns the same context for chaining.
+
+```typescript
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+## ResponseCacheContextOptions
+
+The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Overrides the auto-derived cache key for this request only.
+
+**scope** (`string | null`): Overrides the tenant scope for this request only. \`null\` opts out of scoping.
+
+**bust** (`boolean`): Skip the cache read but still write on completion.
+
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they are instance-level concerns that should not vary per request.
+
+## ResponseCacheKeyInputs
+
+The argument passed to a `key` function (constructor or per-call). All fields contribute to the deterministic hash by default.
+
+**agentId** (`string`): Logical processor id used to namespace the cache key.
+
+**scope** (`string | null | undefined`): Resolved scope for this request, or \`null\` when scoping is disabled.
+
+**model** (`{ provider?: string; modelId?: string; specVersion?: string }`): Provider/model identity. Different models produce different responses.
+
+**prompt** (`LanguageModelV2Prompt`): The exact prompt the provider would receive, post memory load and post any prompt-modifying input processors.
+
+**stepNumber** (`number`): 0-indexed step number within the agentic loop. Greater than zero for tool steps.
+
+## Helper exports
+
+- `buildResponseCacheKey(inputs)` — the deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
+- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS` — the default `ttl` (`300`).
+- `RESPONSE_CACHE_CONTEXT_KEY` — the `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline); prefer the helpers.
+
+## Related
+
+- [Response caching](https://mastra.ai/docs/agents/response-caching)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Processor interface](https://mastra.ai/reference/processors/processor-interface)

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,20 @@
 # @mastra/mcp-docs-server
 
+## 1.1.35-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [[`7c275a8`](https://github.com/mastra-ai/mastra/commit/7c275a810595e1a6c41ccc39720531ab65734700), [`890b24c`](https://github.com/mastra-ai/mastra/commit/890b24cc7d32ed6aa4dfe253e54dc6bf4099f690), [`0f48ebf`](https://github.com/mastra-ai/mastra/commit/0f48ebfc7ac7897b2092a189f45751924cf56d1c), [`f180e49`](https://github.com/mastra-ai/mastra/commit/f180e4990e71b04c9a475b523584071712f0048f), [`9260e01`](https://github.com/mastra-ai/mastra/commit/9260e015276fb1b500f7878ee452b47476bf1583), [`2f6c54e`](https://github.com/mastra-ai/mastra/commit/2f6c54e17c041cac1def54baaa6b771647836414), [`e06a159`](https://github.com/mastra-ai/mastra/commit/e06a1598ca07a6c3778aefc2a2d288363c6294ff), [`db34bc6`](https://github.com/mastra-ai/mastra/commit/db34bc6fb36cf125bda0c46be4d3fdc774b70cc4)]:
+  - @mastra/core@1.33.0-alpha.8
+  - @mastra/mcp@1.7.0
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.35-alpha.13",
+  "version": "1.1.35-alpha.17",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.33.0-alpha.6",
+    "@mastra/core": "1.33.0-alpha.8",
     "@mastra/mcp": "^1.7.0"
   },
   "devDependencies": {
@@ -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.6"
+    "@mastra/core": "1.33.0-alpha.8"
   },
   "homepage": "https://mastra.ai",
   "repository": {