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

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

@@ -0,0 +1,148 @@
+# Response caching
+
+Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to drop latency to single-digit milliseconds and avoid paying for repeated calls.
+
+Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. There is no agent-level option — to enable caching, register the processor explicitly. This keeps the API surface small while we collect feedback; per-call overrides flow through `RequestContext`.
+
+## When to use response caching
+
+Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
+
+## Quickstart
+
+Add a `ResponseCache` to the agent's `inputProcessors` and pass any `MastraServerCache` as the backend. For development, `InMemoryServerCache` works out of the box:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+export const searchAgent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })], // 10 minutes
+})
+```
+
+The first call runs the LLM normally and writes the response to the cache. Subsequent calls with an identical resolved prompt return the cached response without invoking the LLM.
+
+## Per-call overrides via RequestContext
+
+Per-call config flows through `RequestContext`. Use `ResponseCache.context()` to build a fresh context, or `ResponseCache.applyContext()` to merge into one you already have:
+
+```typescript
+import { ResponseCache } from '@mastra/core/processors'
+import { RequestContext } from '@mastra/core/request-context'
+
+// Fresh context with the override
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom-key', bust: true }),
+})
+
+// Or merge into an existing context
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+Three fields are overridable per call:
+
+- `key` — string or function. Overrides the auto-derived cache key for this request only.
+- `scope` — string or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
+- `bust` — boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
+
+`cache`, `ttl`, and `agentId` stay on the constructor — they are instance-level concerns and not safe to vary per call.
+
+## Tenant scoping
+
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically — two users never see each other's cached responses.
+
+Override explicitly when you need a different scope:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: [
+    new ResponseCache({
+      cache,
+      scope: 'org-123', // explicit tenant scope
+    }),
+  ],
+})
+```
+
+Pass `scope: null` to deliberately share entries across all callers — only use this for known-public, non-personalized content.
+
+## Custom cache backend
+
+`ResponseCache` accepts any `MastraServerCache`. For production, use `RedisCache` from `@mastra/redis`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ResponseCache } from '@mastra/core/processors'
+import { RedisCache } from '@mastra/redis'
+
+const cache = new RedisCache({ url: process.env.REDIS_URL })
+
+export const agent = new Agent({
+  name: 'Cached Agent',
+  instructions: '...',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache })],
+})
+```
+
+For a custom backend, extend `MastraServerCache` and implement its abstract methods (the processor only calls `get` and `set`).
+
+## How caching is implemented
+
+`ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
+
+This means 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 run — and each step in an agentic tool loop is independently cached.
+
+## What's in the cache key
+
+When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
+
+### Customize the cache key
+
+Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):
+
+```typescript
+import { ResponseCache, buildResponseCacheKey } from '@mastra/core/processors'
+
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    // Cache only on the model id and the resolved prompt tail — ignore
+    // step number, scope, etc.
+    key: ({ model, prompt }) => `qa:${model.modelId}:${JSON.stringify(prompt).slice(-200)}`,
+  }),
+})
+
+// Or reuse the deterministic helper while overriding individual fields:
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    key: inputs => buildResponseCacheKey({ ...inputs, scope: 'global' }),
+  }),
+})
+```
+
+If the function throws, the processor falls back to the default key derivation so the call still benefits from caching.
+
+## How cache hits work
+
+When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
+
+Cache writes happen after the response completes. Failed runs (errors, tripwire activations) are not cached, so the next call retries cleanly.
+
+## Related
+
+- [`ResponseCache` reference](https://mastra.ai/reference/processors/response-cache)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
+- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.generate()](https://mastra.ai/reference/agents/generate)

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/memory/observational-memory.md

@@ -77,6 +77,48 @@ The observer also sees these markers when it processes the thread, so the observ
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
+## Early activation
+
+OM can activate buffered observations before the token threshold is reached. This is useful when a prompt cache is likely to expire, or when the agent changes model providers.
+
+Top-level early activation settings apply to observations by default:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      observation: {
+        activateAfterIdle: false,
+      },
+      reflection: {
+        activateAfterIdle: '10m',
+        activateOnProviderChange: true,
+      },
+    },
+  },
+})
+```
+
+In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
@@ -368,17 +410,19 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                        | Default | What it controls                                                                                                                                                                                                                                                                                                                       |
-| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                     |
-| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                  |
-| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                                   |
-| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
-| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                   |
-| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                   |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                            |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                         |
+| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                          |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, or duration strings like `"5m"` or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                          |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                          |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                      |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                    |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                   |
 
-If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
 ```typescript
 const memory = new Memory({
@@ -392,9 +436,9 @@ const memory = new Memory({
 })
 ```
 
-With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+With a 5-minute prompt cache TTL, this activates buffered observations after 5 minutes of inactivity so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer, `300_000` works the same way.
 
-Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
 ### Disabling
 

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/arize.md

@@ -43,7 +43,7 @@ Phoenix is an open-source observability platform that can be self-hosted or used
 
 ```bash
 # Required
-PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
+PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
 
 # Optional
 PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
@@ -87,7 +87,7 @@ export const mastra = new Mastra({
         serviceName: process.env.PHOENIX_PROJECT_NAME || 'mastra-service',
         exporters: [
           new ArizeExporter({
-            endpoint: process.env.PHOENIX_ENDPOINT!,
+            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
             apiKey: process.env.PHOENIX_API_KEY,
             projectName: process.env.PHOENIX_PROJECT_NAME,
           }),
@@ -106,7 +106,7 @@ export const mastra = new Mastra({
 >   arizephoenix/phoenix:latest
 > ```
 >
-> Set `PHOENIX_ENDPOINT=http://localhost:6006/v1/traces` and run your Mastra agent to see traces at [localhost:6006](http://localhost:6006).
+> Set `PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces` and run your Mastra agent to see traces at [localhost:6006](http://localhost:6006).
 
 ### Arize AX Setup
 
@@ -218,7 +218,7 @@ Control how traces are batched and exported:
 
 ```typescript
 new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
+  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
   apiKey: process.env.PHOENIX_API_KEY,
 
   // Batch processing configuration
@@ -233,7 +233,7 @@ Add custom attributes to all exported spans:
 
 ```typescript
 new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
+  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
   resourceAttributes: {
     'deployment.environment': process.env.NODE_ENV,
     'service.namespace': 'production',

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/observability/tracing/overview.md

@@ -292,7 +292,7 @@ export const mastra = new Mastra({
         serviceName: 'my-service',
         exporters: [
           new ArizeExporter({
-            endpoint: process.env.PHOENIX_ENDPOINT,
+            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
             apiKey: process.env.PHOENIX_API_KEY,
           }),
           new DefaultExporter(), // Keep Studio access

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 3887 models from 108 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3897 models from 108 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/llmgateway.md

@@ -1,6 +1,6 @@
 # ![LLM Gateway logo](https://models.dev/logos/llmgateway.svg)LLM Gateway
 
-Access 189 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
+Access 195 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
 
 Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
 
@@ -66,6 +66,7 @@ for await (const chunk of stream) {
 | `llmgateway/gemini-2.5-flash-lite-preview-09-2025` | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
 | `llmgateway/gemini-2.5-pro`                        | 1.0M    |       |           |       |       |       | $1         | $10         |
 | `llmgateway/gemini-3-flash-preview`                | 1.0M    |       |           |       |       |       | $0.50      | $3          |
+| `llmgateway/gemini-3.1-flash-lite`                 | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `llmgateway/gemini-3.1-flash-lite-preview`         | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `llmgateway/gemini-3.1-pro-preview`                | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `llmgateway/gemini-pro-latest`                     | 1.0M    |       |           |       |       |       | $2         | $12         |
@@ -132,6 +133,7 @@ for await (const chunk of stream) {
 | `llmgateway/grok-4-1-fast-reasoning`               | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
 | `llmgateway/grok-4-20-beta-0309-non-reasoning`     | 2.0M    |       |           |       |       |       | $2         | $6          |
 | `llmgateway/grok-4-20-beta-0309-reasoning`         | 2.0M    |       |           |       |       |       | $2         | $6          |
+| `llmgateway/grok-4-3`                              | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `llmgateway/grok-4-fast`                           | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
 | `llmgateway/grok-4-fast-non-reasoning`             | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
 | `llmgateway/grok-4-fast-reasoning`                 | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
@@ -154,6 +156,10 @@ for await (const chunk of stream) {
 | `llmgateway/llama-4-scout`                         | 33K     |       |           |       |       |       | $0.18      | $0.59       |
 | `llmgateway/llama-4-scout-17b-instruct`            | 8K      |       |           |       |       |       | $0.17      | $0.66       |
 | `llmgateway/mimo-v2-flash`                         | 262K    |       |           |       |       |       | $0.10      | $0.30       |
+| `llmgateway/mimo-v2-omni`                          | 262K    |       |           |       |       |       | $0.40      | $2          |
+| `llmgateway/mimo-v2-pro`                           | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `llmgateway/mimo-v2.5`                             | 1.0M    |       |           |       |       |       | $0.40      | $2          |
+| `llmgateway/mimo-v2.5-pro`                         | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `llmgateway/minimax-m2`                            | 197K    |       |           |       |       |       | $0.30      | $1          |
 | `llmgateway/minimax-m2.1`                          | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `llmgateway/minimax-m2.1-lightning`                | 197K    |       |           |       |       |       | $0.12      | $0.48       |

package/.docs/models/providers/nebius.md

@@ -1,6 +1,6 @@
 # ![Nebius Token Factory logo](https://models.dev/logos/nebius.svg)Nebius Token Factory
 
-Access 30 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
+Access 31 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
 
 Learn more in the [Nebius Token Factory documentation](https://docs.tokenfactory.nebius.com/).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 | ------------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `nebius/deepseek-ai/DeepSeek-V3.2`               | 163K    |       |           |       |       |       | $0.30      | $0.45       |
 | `nebius/deepseek-ai/DeepSeek-V3.2-fast`          | 8K      |       |           |       |       |       | $0.40      | $2          |
+| `nebius/deepseek-ai/DeepSeek-V4-Pro`             | 1.0M    |       |           |       |       |       | $2         | $4          |
 | `nebius/google/gemma-2-2b-it`                    | 8K      |       |           |       |       |       | $0.02      | $0.06       |
 | `nebius/google/gemma-3-27b-it`                   | 110K    |       |           |       |       |       | $0.10      | $0.30       |
 | `nebius/meta-llama/Llama-3.3-70B-Instruct`       | 128K    |       |           |       |       |       | $0.13      | $0.40       |