@mastra/mcp-docs-server 1.1.17-alpha.9 → 1.1.18-alpha.1

package/.docs/models/providers/vultr.md

@@ -1,6 +1,6 @@
 # ![Vultr logo](https://models.dev/logos/vultr.svg)Vultr
 
-Access 9 Vultr models through Mastra's model router. Authentication is handled automatically using the `VULTR_API_KEY` environment variable.
+Access 4 Vultr models through Mastra's model router. Authentication is handled automatically using the `VULTR_API_KEY` environment variable.
 
 Learn more in the [Vultr documentation](https://api.vultrinference.com/).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "vultr/DeepSeek-R1-Distill-Llama-70B"
+  model: "vultr/DeepSeek-V3.2"
 });
 
 // Generate a response
@@ -32,17 +32,12 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                           | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ----------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `vultr/DeepSeek-R1-Distill-Llama-70B`           | 130K    |       |           |       |       |       | $2         | $2          |
-| `vultr/DeepSeek-R1-Distill-Qwen-32B`            | 130K    |       |           |       |       |       | $0.30      | $0.30       |
-| `vultr/DeepSeek-V3.2`                           | 163K    |       |           |       |       |       | $0.55      | $2          |
-| `vultr/GLM-5-FP8`                               | 202K    |       |           |       |       |       | $0.85      | $3          |
-| `vultr/gpt-oss-120b`                            | 130K    |       |           |       |       |       | $0.15      | $0.60       |
-| `vultr/Kimi-K2.5`                               | 261K    |       |           |       |       |       | $0.55      | $3          |
-| `vultr/Llama-3_1-Nemotron-Ultra-253B-v1`        | 32K     |       |           |       |       |       | $0.55      | $2          |
-| `vultr/MiniMax-M2.5`                            | 196K    |       |           |       |       |       | $0.30      | $1          |
-| `vultr/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4` | 260K    |       |           |       |       |       | $0.20      | $0.80       |
+| Model                 | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `vultr/DeepSeek-V3.2` | 163K    |       |           |       |       |       | $0.55      | $2          |
+| `vultr/GLM-5-FP8`     | 202K    |       |           |       |       |       | $0.85      | $3          |
+| `vultr/Kimi-K2.5`     | 261K    |       |           |       |       |       | $0.55      | $3          |
+| `vultr/MiniMax-M2.5`  | 196K    |       |           |       |       |       | $0.30      | $1          |
 
 ## Advanced configuration
 
@@ -54,7 +49,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.vultrinference.com/v1",
-    id: "vultr/DeepSeek-R1-Distill-Llama-70B",
+    id: "vultr/DeepSeek-V3.2",
     apiKey: process.env.VULTR_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -72,8 +67,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "vultr/gpt-oss-120b"
-      : "vultr/DeepSeek-R1-Distill-Llama-70B";
+      ? "vultr/MiniMax-M2.5"
+      : "vultr/DeepSeek-V3.2";
   }
 });
 ```

package/.docs/models/providers/zai-coding-plan.md

@@ -1,6 +1,6 @@
 # ![Z.AI Coding Plan logo](https://models.dev/logos/zai-coding-plan.svg)Z.AI Coding Plan
 
-Access 11 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 12 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Z.AI Coding Plan documentation](https://docs.z.ai/devpack/overview).
 
@@ -45,6 +45,7 @@ for await (const chunk of stream) {
 | `zai-coding-plan/glm-4.7-flashx` | 200K    |       |           |       |       |       | $0.07      | $0.40       |
 | `zai-coding-plan/glm-5`          | 205K    |       |           |       |       |       | —          | —           |
 | `zai-coding-plan/glm-5-turbo`    | 200K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5.1`        | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -74,7 +75,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zai-coding-plan/glm-5-turbo"
+      ? "zai-coding-plan/glm-5.1"
       : "zai-coding-plan/glm-4.5";
   }
 });

package/.docs/models/providers/zenmux.md

@@ -1,6 +1,6 @@
 # ![ZenMux logo](https://models.dev/logos/zenmux.svg)ZenMux
 
-Access 86 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
+Access 85 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
 
 Learn more in the [ZenMux documentation](https://docs.zenmux.ai).
 
@@ -52,7 +52,6 @@ for await (const chunk of stream) {
 | `zenmux/google/gemini-2.5-flash-lite`         | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
 | `zenmux/google/gemini-2.5-pro`                | 1.0M    |       |           |       |       |       | $1         | $10         |
 | `zenmux/google/gemini-3-flash-preview`        | 1.0M    |       |           |       |       |       | $0.50      | $3          |
-| `zenmux/google/gemini-3-pro-image-preview`    | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `zenmux/google/gemini-3-pro-preview`          | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `zenmux/google/gemini-3.1-flash-lite-preview` | 1.1M    |       |           |       |       |       | $0.25      | $2          |
 | `zenmux/google/gemini-3.1-pro-preview`        | 1.0M    |       |           |       |       |       | $2         | $12         |
@@ -130,7 +129,7 @@ const agent = new Agent({
   id: "custom-agent",
   name: "custom-agent",
   model: {
-    url: "https://zenmux.ai/api/anthropic/v1",
+    url: "https://zenmux.ai/api/v1",
     id: "zenmux/anthropic/claude-3.5-haiku",
     apiKey: process.env.ZENMUX_API_KEY,
     headers: {
@@ -153,32 +152,4 @@ const agent = new Agent({
       : "zenmux/anthropic/claude-3.5-haiku";
   }
 });
-```
-
-## Direct provider installation
-
-This provider can also be installed directly as a standalone package, which can be used instead of the Mastra model router string. View the [package documentation](https://www.npmjs.com/package/@ai-sdk/anthropic) for more details.
-
-**npm**:
-
-```bash
-npm install @ai-sdk/anthropic
-```
-
-**pnpm**:
-
-```bash
-pnpm add @ai-sdk/anthropic
-```
-
-**Yarn**:
-
-```bash
-yarn add @ai-sdk/anthropic
-```
-
-**Bun**:
-
-```bash
-bun add @ai-sdk/anthropic
 ```

package/.docs/models/providers/zhipuai-coding-plan.md

@@ -1,6 +1,6 @@
 # ![Zhipu AI Coding Plan logo](https://models.dev/logos/zhipuai-coding-plan.svg)Zhipu AI Coding Plan
 
-Access 12 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 13 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview).
 
@@ -46,6 +46,7 @@ for await (const chunk of stream) {
 | `zhipuai-coding-plan/glm-4.7-flashx` | 200K    |       |           |       |       |       | $0.07      | $0.40       |
 | `zhipuai-coding-plan/glm-5`          | 205K    |       |           |       |       |       | —          | —           |
 | `zhipuai-coding-plan/glm-5-turbo`    | 200K    |       |           |       |       |       | —          | —           |
+| `zhipuai-coding-plan/glm-5.1`        | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -75,7 +76,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zhipuai-coding-plan/glm-5-turbo"
+      ? "zhipuai-coding-plan/glm-5.1"
       : "zhipuai-coding-plan/glm-4.5";
   }
 });

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -59,4 +59,6 @@ export async function POST(req: Request) {
 
 **sendSources** (`boolean`): Whether to include source citations in the stream. (Default: `false`)
 
+**onError** (`(error: unknown) => string`): Called when the stream encounters an error. Return the string that will be sent to the client as the error message. Use this to sanitize errors before they reach the client — for example, to prevent internal infrastructure details from leaking to end users.
+
 **messageMetadata** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): A function that receives the current stream part and returns metadata to attach to start and finish chunks. See the \[AI SDK message metadata docs]\(https\://ai-sdk.dev/docs/ai-sdk-ui/message-metadata) for details.

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

@@ -308,7 +308,7 @@ response.processDataStream({
 
 ## Stored agents
 
-Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated. Memory is configured inline as a `SerializedMemoryConfig` object with options such as `lastMessages` and `semanticRecall`.
 
 ### `listStoredAgents()`
 
@@ -361,10 +361,15 @@ const agent = await mastraClient.createStoredAgent({
     provider: 'openai',
     name: 'gpt-5.4',
   },
-  tools: ['calculator', 'weather'],
-  workflows: ['data-processing'],
-  agents: ['subagent-1'],
-  memory: 'my-memory',
+  tools: { calculator: {}, weather: {} },
+  workflows: { 'data-processing': {} },
+  agents: { 'subagent-1': {} },
+  memory: {
+    options: {
+      lastMessages: 20,
+      semanticRecall: false,
+    },
+  },
   scorers: {
     'quality-scorer': {
       sampling: { type: 'ratio', rate: 0.1 },
@@ -415,7 +420,7 @@ const updated = await storedAgent.update({
 ```typescript
 // Update just the tools
 await storedAgent.update({
-  tools: ['new-tool-1', 'new-tool-2'],
+  tools: { 'new-tool-1': {}, 'new-tool-2': {} },
 })
 
 // Update metadata

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

@@ -32,7 +32,7 @@ export const mastraClient = new MastraClient({
 
 **getAgent(agentId)** (`Agent`): Retrieves a specific agent instance by ID.
 
-**getMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
+**listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
 
 **createMemoryThread(params)** (`Promise<MemoryThread>`): Creates a new memory thread with the given parameters.
 

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

@@ -7,7 +7,7 @@ The Memory API provides methods to manage conversation threads and message histo
 Retrieve all memory threads for a specific resource:
 
 ```typescript
-const threads = await mastraClient.getMemoryThreads({
+const threads = await mastraClient.listMemoryThreads({
   resourceId: 'resource-1',
   agentId: 'agent-1', // Optional - can be omitted if storage is configured
 })

package/.docs/reference/configuration.md

@@ -566,6 +566,30 @@ export const mastra = new Mastra({
 })
 ```
 
+### server.mcpOptions
+
+**Type:** `object`\
+**Default:** `undefined`
+
+MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state are not available.
+
+| Property             | Type           | Default     | Description                                          |
+| -------------------- | -------------- | ----------- | ---------------------------------------------------- |
+| `serverless`         | `boolean`      | `false`     | Run MCP in stateless mode without session management |
+| `sessionIdGenerator` | `() => string` | `undefined` | Custom session ID generator function                 |
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    mcpOptions: {
+      serverless: true,
+    },
+  },
+})
+```
+
 ### server.build
 
 Build-time configuration for server features. These options control development tools like Swagger UI and request logging, which are enabled during local development but disabled in production by default.

package/.docs/reference/core/mastra-model-gateway.md

@@ -87,6 +87,8 @@ Fetches provider configurations from the gateway.
 
 Builds the API URL for a specific model/provider combination.
 
+If your provider URL contains placeholders such as `${ACCOUNT_ID}`, resolve them inside `buildUrl()` from `envVars` or `process.env` before returning the final URL.
+
 **Parameters:**
 
 **modelId** (`string`): Full model ID (e.g., "custom/my-provider/model-1")

package/.docs/reference/deployer/cloudflare.md

@@ -87,4 +87,34 @@ Use `vars` in the `CloudflareDeployer` constructor only for non-sensitive config
 
 ## Build output
 
-After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+
+## Cloudflare bindings
+
+When you use the Cloudflare deployer, you can import runtime bindings from `cloudflare:workers` in your Mastra config file. Mastra automatically preserves protocol-based runtime imports like `cloudflare:workers` during `mastra build` without trying to install them as npm dependencies.
+
+```typescript
+import { env } from 'cloudflare:workers'
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: 'my-worker',
+    kv_namespaces: [{ binding: 'CACHE', id: 'your-kv-namespace-id' }],
+  }),
+  server: {
+    apiRoutes: [
+      registerApiRoute('/bindings', {
+        method: 'GET',
+        requiresAuth: false,
+        handler: async c => {
+          await env.CACHE.put('status', 'ok')
+          return c.json({ status: await env.CACHE.get('status') })
+        },
+      }),
+    ],
+  },
+})
+```

package/.docs/reference/evals/scorer-utils.md

@@ -367,10 +367,11 @@ The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{
 import { compareTrajectories } from '@mastra/evals/scorers/utils'
 
 // Using ExpectedStep[] (recommended for expectations)
+// Data fields (e.g. toolArgs) are auto-compared when present on expected steps
 const result = compareTrajectories(
   actualTrajectory,
   { steps: [{ name: 'search' }, { name: 'summarize', stepType: 'tool_call' }] },
-  { compareStepData: false, allowRepeatedSteps: true },
+  { allowRepeatedSteps: true },
 )
 // result.score — 0.0 to 1.0
 // result.missingSteps — step names not found
@@ -412,7 +413,9 @@ const result = checkTrajectoryEfficiency(trajectory, {
 })
 // result.score — 1.0 if within all budgets, lower with penalties
 // result.redundantCalls — duplicate tool+args combos
-// result.overBudget — which budgets were exceeded
+// result.overStepBudget — true if maxSteps exceeded
+// result.overTokenBudget — true if maxTotalTokens exceeded
+// result.overDurationBudget — true if maxTotalDurationMs exceeded
 ```
 
 **Returns:** `TrajectoryEfficiencyResult`
@@ -428,8 +431,9 @@ const result = checkTrajectoryBlacklist(trajectory, {
   blacklistedTools: ['deleteAll', 'admin-override'],
   blacklistedSequences: [['escalate', 'admin-override']],
 })
-// result.passed — true if no violations
-// result.violations — list of violations with type and details
+// result.score — 1.0 if no violations, 0.0 if any found
+// result.violatedTools — blacklisted tools that were called
+// result.violatedSequences — blacklisted sequences that were detected
 ```
 
 **Returns:** `TrajectoryBlacklistResult`
@@ -442,7 +446,7 @@ Detects tool failure patterns including retries, fallbacks, and argument correct
 import { analyzeToolFailures } from '@mastra/evals/scorers/utils'
 
 const result = analyzeToolFailures(trajectory, {
-  maxRetriesPerTool: 3,
+  maxRetriesPerTool: 2,
 })
 // result.score — 1.0 if no failure patterns, lower if patterns detected
 // result.patterns — detected patterns (retry, fallback, arg_correction)

package/.docs/reference/evals/trajectory-accuracy.md

@@ -103,13 +103,15 @@ All step types share the base properties `name`, `durationMs`, `metadata`, and `
 
 ## Expected steps
 
-When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a simpler type designed for expectations:
+When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a discriminated union that mirrors `TrajectoryStep` — when you specify a `stepType`, you get autocomplete for that variant's fields (e.g., `toolArgs` for `tool_call`, `modelId` for `model_generation`). All variant-specific fields are optional, so you only assert against what you care about.
+
+Omit `stepType` entirely to match any step by name only.
 
 **name** (`string`): Step name to match (tool name, agent ID, workflow step name, etc.).
 
-**stepType** (`TrajectoryStepType`): Step type to match. If omitted, matches any step type with the given name.
+**stepType** (`TrajectoryStepType`): Step type discriminant. When set, enables autocomplete for that variant's fields. If omitted, matches any step type with the given name.
 
-**data** (`Record<string, unknown>`): Expected step data. Compared against the actual step's type-specific data (toolArgs for tool\_call, output for workflow\_step, etc.).
+**(variant fields)** (`varies`): Type-specific fields from the corresponding TrajectoryStep variant. For example, \`toolArgs\` and \`toolResult\` for \`tool\_call\`, \`modelId\` for \`model\_generation\`, \`output\` for \`workflow\_step\`. All optional — only specified fields are compared.
 
 **children** (`TrajectoryExpectation`): Nested expectation config for this step's children. Overrides the parent config for evaluating children of this step.
 
@@ -120,11 +122,14 @@ const steps: ExpectedStep[] = [
   // Match by name only (any step type)
   { name: 'search' },
 
-  // Match by name and step type
+  // Match by name and step type (autocomplete for tool_call fields)
   { name: 'search', stepType: 'tool_call' },
 
-  // Match with expected data
-  { name: 'search', stepType: 'tool_call', data: { input: { query: 'weather' } } },
+  // Match with specific toolArgs (auto-compared when present)
+  { name: 'search', stepType: 'tool_call', toolArgs: { query: 'weather' } },
+
+  // Match a model generation step by model ID
+  { name: 'gpt-4o', stepType: 'model_generation', modelId: 'gpt-4o' },
 ]
 ```
 
@@ -182,7 +187,7 @@ The `createTrajectoryAccuracyScorerCode()` function from `@mastra/evals/scorers/
 
 ### Parameters
 
-**expectedTrajectory** (`TrajectoryExpectation`): Static expected trajectory to compare against. When provided, all dataset items use this trajectory. When omitted, the scorer reads expectedTrajectory from each dataset item at runtime.
+**expectedTrajectory** (`Trajectory | ExpectedStep[]`): Static expected trajectory to compare against. Accepts a full Trajectory or an array of ExpectedStep matchers. When omitted, the scorer reads expectedTrajectory from each dataset item at runtime.
 
 **comparisonOptions** (`TrajectoryComparisonOptions`): Controls how the comparison is performed.
 
@@ -368,8 +373,8 @@ const scorer = createTrajectoryAccuracyScorerCode({
       },
     ],
   },
-  comparisonOptions: { compareStepData: true },
 })
+// Data fields like toolArgs are auto-compared when present on expected steps
 ```
 
 ## LLM-based trajectory accuracy scorer
@@ -380,7 +385,7 @@ The `createTrajectoryAccuracyScorerLLM()` function from `@mastra/evals/scorers/p
 
 **model** (`MastraModelConfig`): The LLM model to use for evaluating trajectory quality.
 
-**expectedTrajectory** (`TrajectoryExpectation`): Optional static expected trajectory to compare against. When omitted, the LLM evaluates the trajectory based on the task requirements alone. Can also come from dataset items at runtime.
+**expectedTrajectory** (`Trajectory | ExpectedStep[]`): Optional static expected trajectory to compare against. Accepts a full Trajectory or an array of ExpectedStep matchers. When omitted, the LLM evaluates the trajectory based on the task requirements alone. Can also come from dataset items at runtime.
 
 ### Features
 
@@ -461,7 +466,7 @@ The `createTrajectoryScorerCode()` function from `@mastra/evals/scorers/prebuilt
 
 **defaults** (`TrajectoryExpectation`): Default expectations applied to all dataset items. Per-item expectedTrajectory values override these defaults.
 
-**weights** (`object`): Weights for combining dimension scores into the final score.
+**weights** (`TrajectoryScoreWeights`): Custom weights for combining dimension scores. Weights are normalized to sum to 1.0.
 
 ### Scoring behavior
 
@@ -472,7 +477,7 @@ The unified scorer evaluates four dimensions:
 3. **Blacklist** — Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
 4. **Tool failures** — Detects retry patterns, fallback patterns, and argument correction patterns.
 
-The final score is a weighted average of accuracy, efficiency, and tool failures. Blacklist violations override everything to 0.
+The final score is a weighted combination of active dimensions, normalized by which dimensions are active. Default weights are accuracy 0.4, efficiency 0.3, tool failures 0.2, blacklist 0.1, but you can customize them via the `weights` option. Blacklist violations override everything to 0. When nested evaluations are present, the score is 70% top-level and 30% nested average.
 
 ### Unified scorer results
 
@@ -481,11 +486,13 @@ The final score is a weighted average of accuracy, efficiency, and tool failures
   runId: string,
   preprocessStepResult: {
     accuracy?: TrajectoryComparisonResult,
-    efficiency: TrajectoryEfficiencyResult,
-    blacklist: TrajectoryBlacklistResult,
-    toolFailures: ToolFailureAnalysisResult,
+    efficiency?: TrajectoryEfficiencyResult,
+    blacklist?: TrajectoryBlacklistResult,
+    toolFailures?: ToolFailureAnalysisResult,
+    nested?: NestedEvaluationResult[],
   },
-  score: number
+  score: number,
+  reason: string
 }
 ```
 
@@ -542,6 +549,13 @@ const scorer = createTrajectoryScorerCode({
     noRedundantCalls: true,
     maxRetriesPerTool: 2,
   },
+  // Customize how dimensions contribute to the final score
+  weights: {
+    accuracy: 0.5, // prioritize step accuracy
+    efficiency: 0.3,
+    toolFailures: 0.1,
+    blacklist: 0.1,
+  },
 })
 ```
 

package/.docs/reference/index.md

@@ -66,7 +66,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getScorerById()](https://mastra.ai/reference/core/getScorerById)
 - [.getServer()](https://mastra.ai/reference/core/getServer)
 - [.getStorage()](https://mastra.ai/reference/core/getStorage)
-- [.getStoredAgentById()](https://mastra.ai/reference/core/getStoredAgentById)
 - [.getTelemetry()](https://mastra.ai/reference/core/getTelemetry)
 - [.getVector()](https://mastra.ai/reference/core/getVector)
 - [.getWorkflow()](https://mastra.ai/reference/core/getWorkflow)
@@ -77,7 +76,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listMCPServers()](https://mastra.ai/reference/core/listMCPServers)
 - [.listMemory()](https://mastra.ai/reference/core/listMemory)
 - [.listScorers()](https://mastra.ai/reference/core/listScorers)
-- [.listStoredAgents()](https://mastra.ai/reference/core/listStoredAgents)
 - [.listVectors()](https://mastra.ai/reference/core/listVectors)
 - [.listWorkflows()](https://mastra.ai/reference/core/listWorkflows)
 - [.setLogger()](https://mastra.ai/reference/core/setLogger)

package/.docs/reference/logging/pino-logger.md

@@ -30,6 +30,64 @@ export const mastra = new Mastra({
 
 **formatters** (`pino.LoggerOptions['formatters']`): Custom Pino formatters for log serialization.
 
+**redact** (`pino.LoggerOptions['redact']`): Paths or options for redacting sensitive fields from log output (Pino \`redact\`).
+
+**prettyPrint** (`boolean`): When false, disables \`pino-pretty\` and writes raw JSON lines (useful for log aggregators). (Default: `true`)
+
+**mixin** (`pino.MixinFn`): Pino mixin function merged into every log object (for example request-scoped \`traceId\` or other shared metadata).
+
+**customLevels** (`Record<string, number>`): Custom log levels and numeric values, forwarded to Pino. Standard severity is still logged via \`debug\`, \`info\`, \`warn\`, and \`error\`; extra levels follow Pino’s custom-level behavior.
+
+## Log enrichment with `mixin`
+
+Use `mixin` when you want the same structured fields on every line (for correlation with the rest of your services):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+
+function getTraceContext() {
+  return { traceId: 'abc-123' }
+}
+
+export const mastra = new Mastra({
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+    mixin() {
+      return getTraceContext()
+    },
+  }),
+})
+```
+
+## Custom levels
+
+`customLevels` is passed through to Pino. `PinoLogger` only exposes `debug`, `info`, `warn`, and `error`; for any extra level name (for example `audit`), subclass and forward to the underlying Pino instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+
+type AuditLevel = 'audit'
+
+class MastraPinoWithAudit extends PinoLogger<AuditLevel> {
+  audit(message: string, meta: Record<string, unknown> = {}) {
+    this.logger.audit(meta, message)
+  }
+}
+
+const logger = new MastraPinoWithAudit({
+  name: 'Mastra',
+  level: 'info',
+  customLevels: { audit: 35 },
+})
+
+export const mastra = new Mastra({ logger })
+```
+
+Numeric values follow Pino’s ordering (built-in levels use 10–60). A level of `35` sits between `info` (30) and `warn` (40), so with `level: 'info'` both `info` and `audit` lines are emitted.
+
 ## File transport (structured logs)
 
 Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.

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

@@ -38,7 +38,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **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`)
 
-**retrieval** (`boolean`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. Retrieval mode is only active when \`scope\` is \`'thread'\`. If you set \`retrieval: true\` with \`scope: 'resource'\`, OM keeps resource-scoped memory behavior but skips retrieval-mode context and does not register the \`recall\` tool. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -578,21 +578,31 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` tool that the agent can call to page through the raw messages behind an observation group's `_range`. The tool is automatically added to the agent's tool list — no manual registration is needed.
+When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list — no manual registration is needed.
 
 ### Parameters
 
-**cursor** (`string`): A message ID to anchor the recall query. Extract the start or end ID from an observation group range (e.g. from \`\_range: \\\`startId:endId\\\`\_\`, use either \`startId\` or \`endId\`). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID.
+**mode** (`'messages' | 'threads' | 'search'`): What to retrieve. \`"messages"\` (default) pages through message history. \`"threads"\` lists all threads for the current user. \`"search"\` finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
 
-**page** (`number`): Pagination offset from the cursor. Positive values page forward (messages after the cursor), negative values page backward (messages before the cursor). \`0\` is treated as \`1\`. (Default: `1`)
+**query** (`string`): Search query for \`mode: "search"\`. Finds messages semantically similar to this text across all threads for the current user.
 
-**limit** (`number`): Maximum number of messages per page. (Default: `20`)
+**cursor** (`string`): A message ID to anchor the recall query. Required for \`mode: "messages"\` when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \`\_range: \\\`startId:endId\\\`\_\`, use either \`startId\` or \`endId\`). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when \`threadId\` is provided to start reading from the beginning of that thread.
+
+**threadId** (`string`): Browse a different thread by its ID. Use \`mode: "threads"\` first to discover thread IDs. When provided without a \`cursor\`, reading starts from the beginning of the thread.
+
+**page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). \`0\` is treated as \`1\` for messages. (Default: `1`)
+
+**limit** (`number`): Maximum number of items to return per page. (Default: `20`)
 
 **detail** (`'low' | 'high'`): Controls how much content is shown per message part. \`'low'\` shows truncated text and tool names with positional indices (\`\[p0]\`, \`\[p1]\`). \`'high'\` shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
 
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \`\[p1]\` — call again with \`partIndex: 1\` to see the full content without loading every part.
 
-### Returns
+**before** (`string`): For \`mode: "threads"\` only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. \`"2026-03-15"\`, \`"2026-03-10T00:00:00Z"\`).
+
+**after** (`string`): For \`mode: "threads"\` only. Filter to threads created after this date. Accepts ISO 8601 format (e.g. \`"2026-03-01"\`, \`"2026-03-10T00:00:00Z"\`).
+
+### Returns (messages mode)
 
 **messages** (`string`): Formatted message content. Format depends on the \`detail\` level.
 
@@ -612,6 +622,22 @@ When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` to
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when \`truncated\` is true.
 
+### Returns (threads mode)
+
+**threads** (`string`): Formatted thread listing. Each thread shows its title, ID, and dates. The current thread is marked with \`← current\`.
+
+**count** (`number`): Number of threads returned.
+
+**page** (`number`): The page number returned.
+
+**hasMore** (`boolean`): Whether more threads exist on the next page.
+
+### Returns (search mode)
+
+**results** (`string`): Formatted search results grouped by thread. Each result shows the thread title, thread ID, relevance score, message preview, and a cursor ID for browsing into that thread.
+
+**count** (`number`): Number of matching messages found.
+
 ### ModelByInputTokens
 
 `ModelByInputTokens` selects a model based on the input token count. It chooses the model for the smallest threshold that covers the actual input size.