@mastra/mcp-docs-server 1.1.32-alpha.4 → 1.1.32-alpha.6

package/.docs/docs/agents/adding-voice.md

@@ -327,19 +327,20 @@ For the complete list of supported AI SDK providers and their capabilities:
 
 Mastra supports multiple voice providers for text-to-speech (TTS) and speech-to-text (STT) capabilities:
 
-| Provider        | Package                         | Features                  | Reference                                                          |
-| --------------- | ------------------------------- | ------------------------- | ------------------------------------------------------------------ |
-| OpenAI          | `@mastra/voice-openai`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
-| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
-| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
-| PlayAI          | `@mastra/voice-playai`          | TTS                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
-| Google          | `@mastra/voice-google`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/google)          |
-| Deepgram        | `@mastra/voice-deepgram`        | STT                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
-| Murf            | `@mastra/voice-murf`            | TTS                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
-| Speechify       | `@mastra/voice-speechify`       | TTS                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
-| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
-| Azure           | `@mastra/voice-azure`           | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
-| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+| Provider        | Package                         | Features                                  | Reference                                                          |
+| --------------- | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| OpenAI          | `@mastra/voice-openai`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
+| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech                 | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
+| AWS Nova Sonic  | `@mastra/voice-aws-nova-sonic`  | Realtime speech-to-speech via AWS Bedrock | [Documentation](https://mastra.ai/reference/voice/aws-nova-sonic)  |
+| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS                          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
+| PlayAI          | `@mastra/voice-playai`          | TTS                                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
+| Google          | `@mastra/voice-google`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/google)          |
+| Deepgram        | `@mastra/voice-deepgram`        | STT                                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
+| Murf            | `@mastra/voice-murf`            | TTS                                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
+| Speechify       | `@mastra/voice-speechify`       | TTS                                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
+| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
+| Azure           | `@mastra/voice-azure`           | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
 
 ## Next steps
 

package/.docs/docs/server/server-adapters.md

@@ -20,6 +20,7 @@ Mastra currently provides these official server adapters:
 - [@mastra/hono](https://mastra.ai/reference/server/hono-adapter)
 - [@mastra/fastify](https://mastra.ai/reference/server/fastify-adapter)
 - [@mastra/koa](https://mastra.ai/reference/server/koa-adapter)
+- [@mastra/nestjs](https://mastra.ai/reference/server/nestjs-adapter)
 
 You can build your own adapter, read [custom adapters](https://mastra.ai/docs/server/custom-adapters) for details.
 
@@ -71,7 +72,7 @@ pnpm add @mastra/express@latest
 yarn add @mastra/express@latest
 ```
 
-**Tab 5**:
+**NestJS**:
 
 ```bash
 bun add @mastra/express@latest
@@ -227,6 +228,56 @@ yarn add @mastra/koa@latest
 bun add @mastra/koa@latest
 ```
 
+**Tab 21**:
+
+**npm**:
+
+```bash
+npm install @mastra/nestjs@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/nestjs@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/nestjs@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/nestjs@latest
+```
+
+**Tab 22**:
+
+```bash
+npm install @mastra/nestjs@latest
+```
+
+**Tab 23**:
+
+```bash
+pnpm add @mastra/nestjs@latest
+```
+
+**Tab 24**:
+
+```bash
+yarn add @mastra/nestjs@latest
+```
+
+**Tab 25**:
+
+```bash
+bun add @mastra/nestjs@latest
+```
+
 ## Configuration
 
 Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
@@ -336,6 +387,37 @@ app.listen(port, () => {
 
 > **Info:** See the [Koa Adapter](https://mastra.ai/reference/server/koa-adapter) documentation for full configuration options.
 
+**NestJS**:
+
+```typescript
+import { Module } from '@nestjs/common'
+import { MastraModule } from '@mastra/nestjs'
+import { mastra } from './mastra'
+
+@Module({
+  imports: [
+    MastraModule.register({
+      mastra,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  await app.listen(3000)
+}
+
+bootstrap()
+```
+
+> **Info:** See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) documentation for full configuration options.
+
 ## Initialization flow
 
 Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
@@ -553,10 +635,11 @@ See [MCP](https://mastra.ai/docs/mcp/overview) for configuration details and how
 
 ## Related
 
-- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter): Hono-specific setup
-- [Express Adapter](https://mastra.ai/reference/server/express-adapter): Express-specific setup
-- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters): Building adapters for other frameworks
-- [Server Configuration](https://mastra.ai/docs/server/mastra-server): Using `mastra build` instead
-- [Authentication](https://mastra.ai/docs/server/auth): Configuring auth for your server
-- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server): Full API reference
-- [createRoute() Reference](https://mastra.ai/reference/server/create-route): Creating type-safe custom routes
+- [Hono Adapter](https://mastra.ai/reference/server/hono-adapter) - Hono-specific setup
+- [Express Adapter](https://mastra.ai/reference/server/express-adapter) - Express-specific setup
+- [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) - NestJS-specific setup
+- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters) - Building adapters for other frameworks
+- [Server Configuration](https://mastra.ai/docs/server/mastra-server) - Using `mastra build` instead
+- [Authentication](https://mastra.ai/docs/server/auth) - Configuring auth for your server
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server) - Full API reference
+- [createRoute() Reference](https://mastra.ai/reference/server/create-route) - Creating type-safe custom routes

package/.docs/docs/voice/overview.md

@@ -588,6 +588,49 @@ await voiceAgent.voice.send(micStream)
 
 Visit the [Google Gemini Live Reference](https://mastra.ai/reference/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
 
+**AWS Nova Sonic**:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
+
+const voiceAgent = new Agent({
+  id: 'voice-agent',
+  name: 'Voice Agent',
+  instructions: 'You are a voice assistant that can help users with their tasks.',
+  model: 'openai/gpt-5.4',
+  voice: new NovaSonicVoice({
+    region: 'us-east-1',
+    speaker: 'matthew',
+    // Static credentials are optional. The default AWS credential
+    // provider chain is used when none are passed.
+  }),
+})
+
+// Connect before using speak/send
+await voiceAgent.voice.connect()
+
+// Listen for assistant audio (Int16Array PCM)
+voiceAgent.voice.on('speaking', ({ audioData }) => {
+  if (audioData) playAudio(audioData)
+})
+
+// Listen for transcribed text
+voiceAgent.voice.on('writing', ({ text, role }) => {
+  console.log(`${role}: ${text}`)
+})
+
+// Initiate the conversation
+await voiceAgent.voice.speak('How can I help you today?')
+
+// Send continuous audio from the microphone
+const micStream = getMicrophoneStream()
+await voiceAgent.voice.send(micStream)
+```
+
+Visit the [AWS Nova Sonic Reference](https://mastra.ai/reference/voice/aws-nova-sonic) for more information on the AWS Nova Sonic voice provider.
+
 ## Voice configuration
 
 Each voice provider can be configured with different models and options. Below are the detailed configuration options for all supported providers:
@@ -828,6 +871,28 @@ const voice = new GeminiLiveVoice({
 
 Visit the [Google Gemini Live Reference](https://mastra.ai/reference/voice/google-gemini-live) for more information on the Google Gemini Live voice provider.
 
+**AWS Nova Sonic**:
+
+```typescript
+// AWS Nova Sonic Voice Configuration
+const voice = new NovaSonicVoice({
+  region: 'us-east-1',
+  speaker: 'matthew',
+  sessionConfig: {
+    inferenceConfiguration: {
+      temperature: 0.7,
+      maxTokens: 1024,
+    },
+    turnDetectionConfiguration: {
+      endpointingSensitivity: 'MEDIUM',
+    },
+  },
+  // AWS Nova Sonic is a realtime bidirectional API without separate speech and listening models
+})
+```
+
+Visit the [AWS Nova Sonic Reference](https://mastra.ai/reference/voice/aws-nova-sonic) for more information on the AWS Nova Sonic voice provider.
+
 **AI SDK**:
 
 ```typescript
@@ -957,6 +1022,7 @@ For more information on the CompositeVoice, refer to the [CompositeVoice Referen
 - [Azure Voice](https://mastra.ai/reference/voice/azure)
 - [Google Voice](https://mastra.ai/reference/voice/google)
 - [Google Gemini Live Voice](https://mastra.ai/reference/voice/google-gemini-live)
+- [AWS Nova Sonic Voice](https://mastra.ai/reference/voice/aws-nova-sonic)
 - [Deepgram Voice](https://mastra.ai/reference/voice/deepgram)
 - [PlayAI Voice](https://mastra.ai/reference/voice/playai)
 - [Voice Examples](https://github.com/mastra-ai/voice-examples)

package/.docs/docs/voice/speech-to-speech.md

@@ -99,4 +99,48 @@ await agent.voice.send(micStream)
 Note:
 
 - Live API requires `GOOGLE_API_KEY`. Vertex AI requires project/location and service account credentials.
-- Events: `speaker` (audio stream), `writing` (text), `turnComplete`, `usage`, and `error`.
+- Events: `speaker` (audio stream), `writing` (text), `turnComplete`, `usage`, and `error`.
+
+## AWS Nova Sonic (Realtime)
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+
+const agent = new Agent({
+  id: 'agent',
+  name: 'Nova Sonic Agent',
+  instructions: 'You are a helpful assistant with real-time voice capabilities.',
+  // Model used for text generation; voice provider handles realtime audio
+  model: 'openai/gpt-5.4',
+  voice: new NovaSonicVoice({
+    region: 'us-east-1',
+    speaker: 'matthew',
+    // Static credentials are optional. The default AWS credential provider
+    // chain is used when none are passed.
+  }),
+})
+
+await agent.voice.connect()
+
+// Assistant audio is emitted as 16-bit PCM on the `speaking` event
+agent.voice.on('speaking', ({ audioData }) => {
+  if (audioData) playAudio(audioData)
+})
+
+agent.voice.on('writing', ({ role, text }) => {
+  console.log(`${role}: ${text}`)
+})
+
+await agent.voice.speak('How can I help you today?')
+
+const micStream = getMicrophoneStream()
+await agent.voice.send(micStream)
+```
+
+Note:
+
+- Available regions: `us-east-1`, `us-west-2`, and `ap-northeast-1`.
+- Authenticates through the standard AWS credential provider chain. Pass `credentials` to override.
+- Events: `speaking` (Int16Array audio), `writing` (text with `generationStage`), `toolCall`, `interrupt`, `turnComplete`, `usage`, `session`, and `error`.

package/.docs/docs/workspace/search.md

@@ -83,6 +83,45 @@ const workspace = new Workspace({
 })
 ```
 
+### Batch embedding
+
+The embedder above takes one text at a time. Indexing a workspace with hundreds of files calls the provider hundreds of times, which is slow and expensive.
+
+When the provider supports batching (for example, OpenAI's `embedMany`), pass an embedder that takes an array of texts and accepts many embeddings back in one call. To opt in, set a `batch: true` property on the function. Mastra checks for that property at runtime and switches to the batched path.
+
+The following example replaces the single-text embedder with a batched one. The embedder function takes an array, returns an array of embeddings in the same order, and carries two extra properties:
+
+- `batch: true`: marks the function as batch-capable. Without this property, Mastra calls it one text at a time.
+- `maxBatchSize`: the largest array the provider accepts in one call. Mastra splits larger requests into chunks of this size and sends them in parallel. Set this to your provider's documented limit (for example, 2048 for OpenAI, 96 for Cohere, 128 for Voyage). Omit it to send every pending text in one request.
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { PineconeVector } from '@mastra/pinecone'
+import { embedMany } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const model = openai.embedding('text-embedding-3-small')
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  vectorStore: new PineconeVector({
+    apiKey: process.env.PINECONE_API_KEY,
+    index: 'workspace-index',
+  }),
+  embedder: Object.assign(
+    async (texts: string[]) => {
+      const { embeddings } = await embedMany({ model, values: texts })
+      return embeddings
+    },
+    { batch: true as const, maxBatchSize: 2048 },
+  ),
+})
+```
+
+`Object.assign` adds the `batch` and `maxBatchSize` properties to the embedder function. Mastra reads them as metadata and never passes them to the provider.
+
+Single-text embedders still work. The function signature `(text: string) => Promise<number[]>` is unchanged, so existing code keeps running without modification.
+
 ## Hybrid search
 
 Configure both BM25 and vector search to enable hybrid mode, which combines keyword matching with semantic understanding.

package/.docs/guides/getting-started/nestjs.md

@@ -0,0 +1,238 @@
+# Integrate Mastra in Your NestJS Project
+
+In this guide, you'll build a tool-calling AI agent using Mastra and NestJS. The [NestJS server adapter](https://mastra.ai/reference/server/nestjs-adapter) registers Mastra's agent and workflow routes as a NestJS module, so they run inside your existing NestJS application.
+
+## Before you begin
+
+- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+- Install Node.js `v22.13.0` or later
+- Use the NestJS Express platform (`@nestjs/platform-express`)
+
+## Create a new NestJS app (optional)
+
+If you already have a NestJS app, skip to the next step.
+
+Run the following command to create a new NestJS app:
+
+**npm**:
+
+```bash
+npx @nestjs/cli new mastra-nest
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx @nestjs/cli new mastra-nest
+```
+
+**Yarn**:
+
+```bash
+yarn dlx @nestjs/cli new mastra-nest
+```
+
+**Bun**:
+
+```bash
+bun x @nestjs/cli new mastra-nest
+```
+
+This creates a project called `mastra-nest`, but you can replace it with any name you want.
+
+## Initialize Mastra
+
+Navigate to your NestJS project directory:
+
+```bash
+cd mastra-nest
+```
+
+Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+**npm**:
+
+```bash
+npx mastra@latest init
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest init
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest init
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest init
+```
+
+This creates a `src/mastra` folder with an example weather agent and the following files:
+
+- `index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+- `agents/weather-agent.ts` - a weather agent with a prompt that uses the tool
+
+You'll pass the `src/mastra/index.ts` file to the NestJS adapter in the next step.
+
+## Add server adapter
+
+Install the NestJS server adapter package:
+
+**npm**:
+
+```bash
+npm install @mastra/nestjs@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/nestjs@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/nestjs@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/nestjs@latest
+```
+
+Open `src/app.module.ts` and register `MastraModule`:
+
+```typescript
+import { Module } from '@nestjs/common'
+import { MastraModule } from '@mastra/nestjs'
+import { mastra } from './mastra'
+
+@Module({
+  imports: [
+    MastraModule.register({
+      mastra,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
+
+## Test your agent
+
+By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
+
+Start your NestJS server:
+
+**npm**:
+
+```bash
+npm run start
+```
+
+**pnpm**:
+
+```bash
+pnpm run start
+```
+
+**Yarn**:
+
+```bash
+yarn run start
+```
+
+**Bun**:
+
+```bash
+bun run start
+```
+
+In a separate terminal window, use `curl` to ask the weather agent:
+
+```bash
+curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
+```
+
+## Use Mastra in Your Own Services
+
+The module exports two ways to access Mastra from your NestJS services: the `MastraService` wrapper and the `MASTRA` injection token.
+
+### MastraService
+
+`MastraService` is an injectable wrapper with convenience methods for common operations:
+
+```typescript
+import { Injectable } from '@nestjs/common'
+import { MastraService } from '@mastra/nestjs'
+
+@Injectable()
+export class AgentService {
+  constructor(private readonly mastraService: MastraService) {}
+
+  async chat(agentId: string, message: string) {
+    const agent = this.mastraService.getAgent(agentId)
+    return agent.generate({
+      messages: [{ role: 'user', content: message }],
+    })
+  }
+
+  async runWorkflow(workflowId: string, input: Record<string, unknown>) {
+    const workflow = this.mastraService.getWorkflow(workflowId)
+    return workflow.start({ inputData: input })
+  }
+}
+```
+
+`MastraService` exposes:
+
+- `getMastra()` — returns the underlying `Mastra` instance
+- `getAgent(id)` — shorthand for `mastra.getAgent(id)`
+- `getWorkflow(id)` — shorthand for `mastra.getWorkflow(id)`
+- `getOptions()` — returns the module configuration
+- `isShuttingDown` — `true` after graceful shutdown begins
+
+### MASTRA token
+
+If you need the `Mastra` instance directly (e.g., to access storage, memory, or other core APIs), inject it with the `MASTRA` token:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common'
+import { MASTRA } from '@mastra/nestjs'
+import type { Mastra } from '@mastra/core/mastra'
+
+@Injectable()
+export class MemoryService {
+  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
+
+  async getThreadMessages(threadId: string) {
+    const memory = this.mastra.getMemory()
+    return memory?.getMessages({ threadId })
+  }
+}
+```
+
+Both approaches use the same singleton `Mastra` instance registered by `MastraModule`.
+
+## Next steps
+
+You now have a working Mastra agent running inside NestJS. To extend the project:
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Using tools](https://mastra.ai/docs/agents/using-tools)
+- [Agent memory](https://mastra.ai/docs/memory/overview)
+
+For details on the NestJS integration:
+
+- [NestJS Adapter reference](https://mastra.ai/reference/server/nestjs-adapter)

package/.docs/reference/datasets/startExperiment.md

@@ -15,7 +15,7 @@ const mastra = new Mastra({
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 
-// Run against a registered agent with scorers
+// Run against a registered agent with a flat scorer list
 const summary = await dataset.startExperiment({
   targetType: 'agent',
   targetId: 'my-agent',
@@ -23,8 +23,34 @@ const summary = await dataset.startExperiment({
   maxConcurrency: 10,
 })
 
+// Or pass the same categorised shape accepted by runEvals
+const summary2 = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'my-agent',
+  scorers: {
+    agent: [accuracyScorer],
+    trajectory: [toolOrderScorer],
+  },
+})
+
+// For workflow targets, score individual steps with their own scorers
+const summary3 = await dataset.startExperiment({
+  targetType: 'workflow',
+  targetId: 'my-workflow',
+  scorers: {
+    workflow: [overallScorer],
+    steps: {
+      'fetch-data': [fetchScorer],
+      transform: [transformScorer],
+    },
+    trajectory: [executionPathScorer],
+  },
+})
+
 console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
 console.log(`Status: ${summary.status}`)
+console.log(`${summary2.succeededCount}/${summary2.totalItems} succeeded`)
+console.log(`Status: ${summary2.status}`)
 ```
 
 ## Parameters
@@ -33,7 +59,7 @@ console.log(`Status: ${summary.status}`)
 
 **targetId** (`string`): ID of the registered target. Use with \`targetType\`.
 
-**scorers** (`(MastraScorer | string)[]`): Scorers to evaluate each result. Pass \`MastraScorer\` instances or registered scorer IDs.
+**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to evaluate each result. Accepts a flat array of \`MastraScorer\` instances or registered scorer IDs, or the same categorised config shape used by \`runEvals\` (\`AgentScorerConfig\` / \`WorkflowScorerConfig\`). Trajectory scorers (\`type: "trajectory"\`) automatically receive a pre-extracted \`Trajectory\` as their output regardless of which form is used. For workflow targets, per-step scorers can be passed via \`scorers: { steps: { stepId: \[...] } }\` and run against each step's output; their results carry the originating \`stepId\` and keep \`targetScope: "span"\` (matching \`runEvals\`).
 
 **name** (`string`): Display name for the experiment.
 

package/.docs/reference/index.md

@@ -191,6 +191,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Hono Adapter](https://mastra.ai/reference/server/hono-adapter)
 - [Koa Adapter](https://mastra.ai/reference/server/koa-adapter)
 - [MastraServer](https://mastra.ai/reference/server/mastra-server)
+- [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter)
 - [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [Overview](https://mastra.ai/reference/storage/overview)
@@ -243,6 +244,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
 - [Turbopuffer Vector Store](https://mastra.ai/reference/vectors/turbopuffer)
 - [Upstash Vector Store](https://mastra.ai/reference/vectors/upstash)
+- [AWS Nova Sonic](https://mastra.ai/reference/voice/aws-nova-sonic)
 - [Azure](https://mastra.ai/reference/voice/azure)
 - [Cloudflare](https://mastra.ai/reference/voice/cloudflare)
 - [Composite Voice](https://mastra.ai/reference/voice/composite-voice)

package/.docs/reference/server/nestjs-adapter.md

@@ -0,0 +1,169 @@
+# NestJS Adapter
+
+The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.
+
+It is intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
+
+> **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the NestJS adapter and ensure your app uses the Express platform:
+
+**npm**:
+
+```bash
+npm install @mastra/nestjs@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/nestjs@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/nestjs@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/nestjs@latest
+```
+
+## Usage example
+
+```typescript
+import { Module } from '@nestjs/common'
+import { MastraModule } from '@mastra/nestjs'
+import { mastra } from './mastra'
+
+@Module({
+  imports: [
+    MastraModule.register({
+      mastra,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
+
+```typescript
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  await app.listen(3000)
+}
+
+bootstrap()
+```
+
+By default, Mastra routes mount under `/api`. Use `prefix` to change it.
+
+## Module options
+
+**mastra** (`Mastra`): Mastra instance
+
+**prefix** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `` `/api` ``)
+
+**rateLimitOptions** (`{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }`): Rate limiting config (enabled by default)
+
+**shutdownOptions** (`{ timeoutMs?: number; notifyClients?: boolean }`): Graceful shutdown configuration
+
+**bodyLimitOptions** (`{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }`): Request body size limits
+
+**streamOptions** (`{ redact?: boolean; heartbeatMs?: number }`): Streaming configuration
+
+**tracingOptions** (`{ enabled?: boolean; serviceName?: string }`): OpenTelemetry tracing configuration
+
+**contextOptions** (`{ strict?: boolean; logWarnings?: boolean }`): Request context parsing config
+
+**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are \`METHOD:PATH\`.
+
+**tools** (`Record<string, Tool>`): Registered tools for the server
+
+**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions** (`{ serverless?: boolean; sessionIdGenerator?: () => string }`): MCP transport options
+
+**auth** (`{ enabled?: boolean; allowQueryApiKey?: boolean }`): Enable Mastra token auth. Disabled by default — most NestJS apps use their own auth guards. Query-string \`apiKey\` auth is opt-in for backward compatibility. (Default: `` `{ enabled: false }` ``)
+
+## Async registration
+
+```typescript
+import { Module } from '@nestjs/common'
+import { ConfigModule, ConfigService } from '@nestjs/config'
+import { MastraModule } from '@mastra/nestjs'
+import { Mastra } from '@mastra/core/mastra'
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    MastraModule.registerAsync({
+      imports: [ConfigModule],
+      useFactory: (config: ConfigService) => ({
+        mastra: new Mastra({
+          agents: {
+            greeter: {
+              name: 'greeter',
+              description: 'Greets the user',
+              model: config.get('MASTRA_MODEL', 'openai/gpt-4o-mini'),
+            },
+          },
+        }),
+        prefix: config.get('MASTRA_PREFIX', '/api'),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Accessing Mastra
+
+Use the `MASTRA` token or `MastraService` in your services:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common'
+import { MASTRA, MastraService } from '@mastra/nestjs'
+import type { Mastra } from '@mastra/core/mastra'
+
+@Injectable()
+export class AgentService {
+  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
+}
+
+@Injectable()
+export class WorkflowService {
+  constructor(private readonly mastraService: MastraService) {}
+}
+```
+
+## MCP routes
+
+MCP endpoints are exposed under the API prefix:
+
+- `POST /api/mcp/:serverId/mcp`
+- `GET /api/mcp/:serverId/sse`
+- `POST /api/mcp/:serverId/messages`
+
+## Health routes
+
+Operational endpoints stay unprefixed on purpose for infrastructure compatibility:
+
+- `GET /health`
+- `GET /ready`
+- `GET /info`
+
+## Related
+
+- [Server Adapters](https://mastra.ai/docs/server/server-adapters)
+- [MastraServer Reference](https://mastra.ai/reference/server/mastra-server)

package/.docs/reference/voice/aws-nova-sonic.md

@@ -0,0 +1,247 @@
+# AWS Nova Sonic voice
+
+The `NovaSonicVoice` class provides real-time speech-to-speech capabilities backed by [AWS Bedrock Nova 2 Sonic](https://docs.aws.amazon.com/nova/latest/userguide/speech.html). It opens a bidirectional stream to the model and emits events for assistant audio, transcribed text, tool calls, turn boundaries, and interruptions.
+
+## Usage example
+
+```typescript
+import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+
+// Initialize using the default AWS credential provider chain
+const voice = new NovaSonicVoice({
+  region: 'us-east-1',
+  speaker: 'matthew',
+})
+
+// Or pass explicit credentials
+const voiceWithCredentials = new NovaSonicVoice({
+  region: 'us-east-1',
+  speaker: 'tiffany',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+})
+
+// Establish the bidirectional stream
+await voice.connect()
+
+// Listen for assistant audio (Int16Array PCM)
+voice.on('speaking', ({ audioData }) => {
+  if (audioData) playAudio(audioData)
+})
+
+// Listen for transcribed text from the user and assistant
+voice.on('writing', ({ text, role, generationStage }) => {
+  console.log(`${role} (${generationStage ?? 'FINAL'}): ${text}`)
+})
+
+// Stream microphone audio in real time
+const microphoneStream = getMicrophoneStream()
+await voice.send(microphoneStream)
+
+// Disconnect when done
+voice.close()
+```
+
+## Authentication
+
+`NovaSonicVoice` uses the AWS SDK credential resolution chain when no `credentials` option is passed. Mastra calls `defaultProvider()` from `@aws-sdk/credential-provider-node`, which checks (in order) environment variables, shared credentials files, IAM role for EC2, ECS, EKS, and other standard sources.
+
+To use static credentials, pass them on the constructor:
+
+```typescript
+new NovaSonicVoice({
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    sessionToken: process.env.AWS_SESSION_TOKEN,
+  },
+})
+```
+
+The voice provider never logs credential values.
+
+## Configuration
+
+### Constructor options
+
+**region** (`'us-east-1' | 'us-west-2' | 'ap-northeast-1'`): AWS region that hosts the Nova Sonic model. (Default: `'us-east-1'`)
+
+**model** (`string`): Bedrock model ID for the bidirectional stream. (Default: `'amazon.nova-2-sonic-v1:0'`)
+
+**credentials** (`AwsCredentialIdentity`): Static AWS credentials. When omitted the default AWS credential provider chain is used.
+
+**speaker** (`string | NovaSonicVoiceConfigDetails`): Default voice for the assistant. Pass a voice ID string such as 'matthew' or an object that includes a language code and gender. (Default: `'matthew'`)
+
+**languageCode** (`NovaSonicLanguageCode`): Language code used for the session. Polyglot voices support all listed languages.
+
+**instructions** (`string`): System prompt sent at session start. Equivalent to calling addInstructions() before connect().
+
+**tools** (`NovaSonicToolConfig[]`): Tools exposed to the model. When the voice instance is attached to an Agent, the Agent's tools are added automatically.
+
+**sessionConfig** (`NovaSonicSessionConfig`): Inference, turn-detection, and tool-choice configuration. See Session configuration below.
+
+**debug** (`boolean`): Enable verbose logging for stream events. Sensitive fields are masked. (Default: `false`)
+
+### Session configuration
+
+`sessionConfig` controls inference parameters and turn-taking behavior. All fields are optional.
+
+**inferenceConfiguration** (`object`): Sampling and decoding parameters.
+
+**inferenceConfiguration.maxTokens** (`number`): Maximum tokens generated per turn.
+
+**inferenceConfiguration.temperature** (`number`): Sampling temperature.
+
+**inferenceConfiguration.topP** (`number`): Nucleus sampling probability.
+
+**inferenceConfiguration.topK** (`number`): Top-k sampling.
+
+**inferenceConfiguration.stopSequences** (`string[]`): Sequences that end generation.
+
+**turnDetectionConfiguration** (`object`): Endpointing sensitivity for turn detection.
+
+**turnDetectionConfiguration.endpointingSensitivity** (`'HIGH' | 'MEDIUM' | 'LOW'`): Pause duration before the model considers a turn complete. HIGH ends turns fastest (about 1.5s pause), MEDIUM is balanced (about 1.75s), LOW waits longest (about 2s).
+
+**toolChoice** (`'auto' | 'any' | { tool: { name: string } }`): How the model decides whether to call a tool.
+
+**enableKnowledgeGrounding** (`boolean`): Enable retrieval-augmented grounding against a Bedrock knowledge base.
+
+**knowledgeBaseConfig** (`{ knowledgeBaseId?: string; dataSourceId?: string }`): Knowledge base used when knowledge grounding is enabled.
+
+## Methods
+
+### `connect()`
+
+Opens the bidirectional stream to AWS Bedrock and sends the initial session, prompt, and system events. Call this before `speak`, `listen`, or `send`.
+
+**options** (`{ requestContext?: RequestContext }`): Optional request context propagated to tool calls made during the session.
+
+Returns: `Promise<void>`
+
+### `speak()`
+
+Synthesizes speech for a text prompt and emits `speaking` events as audio is produced.
+
+**input** (`string | NodeJS.ReadableStream`): Text or text stream to synthesize.
+
+**options** (`NovaSonicVoiceOptions`): Per-call overrides such as the speaker or language code.
+
+Returns: `Promise<void>`
+
+### `send()`
+
+Streams microphone audio (or any PCM source) to the model. Use this for live, continuous conversation.
+
+**audioData** (`NodeJS.ReadableStream | Int16Array`): 16-bit PCM audio to forward to the model.
+
+Returns: `Promise<void>`
+
+### `listen()`
+
+Convenience wrapper that delegates to `send()`. Use it when you want a single transcription pass over a finite audio stream.
+
+**audioData** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+Returns: `Promise<void>`
+
+### `endAudioInput()`
+
+Signals the end of the current audio turn so the model can finalize its response. Call this when the user stops speaking and the provider is not configured for server-side turn detection.
+
+Returns: `Promise<void>`
+
+### `addInstructions()`
+
+Updates the system prompt for the active session.
+
+**instructions** (`string`): System prompt to apply to the session.
+
+Returns: `void`
+
+### `addTools()`
+
+Registers tools with the voice instance. When `NovaSonicVoice` is attached to an Agent, the Agent's tools are added automatically.
+
+**tools** (`ToolsInput`): Tools exposed to the model.
+
+Returns: `void`
+
+### `getSpeakers()`
+
+Returns the list of voices supported by Nova 2 Sonic.
+
+Returns: `Promise<Array<{ voiceId: string; name: string; language: string; locale: string; gender: 'masculine' | 'feminine'; polyglot: boolean }>>`
+
+### `getListener()`
+
+Returns whether the voice instance currently holds an open stream.
+
+Returns: `Promise<{ enabled: boolean }>`
+
+### `close()`
+
+Closes the bidirectional stream and destroys the underlying Bedrock client. Call this when the conversation ends.
+
+Returns: `void`
+
+### `on()` / `off()`
+
+Registers and removes event listeners. See [Voice events](https://mastra.ai/reference/voice/voice.events) for the shared event API.
+
+## Events
+
+`NovaSonicVoice` emits the following events:
+
+**speaking** (`event`): Assistant audio chunk. Callback receives { audioData: Int16Array, sampleRate?: number }.
+
+**writing** (`event`): Transcribed text from the user or assistant. Callback receives { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }.
+
+**toolCall** (`event`): Model requested a tool call. Callback receives { name: string, args: Record\<string, any>, id: string }.
+
+**interrupt** (`event`): User or model interrupted the current turn. Callback receives { type: 'user' | 'model', timestamp: number }.
+
+**turnComplete** (`event`): Model finished its turn. Callback receives { timestamp: number }.
+
+**session** (`event`): Session state transition. Callback receives { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }.
+
+**usage** (`event`): Token usage for the turn. Callback receives { inputTokens: number, outputTokens: number, totalTokens: number }.
+
+**error** (`event`): Stream or provider error. Callback receives { message: string, code?: string, details?: unknown }.
+
+`generationStage` distinguishes provisional transcripts (`'SPECULATIVE'`) from finalized ones (`'FINAL'`). Use `'FINAL'` text for persistent storage and `'SPECULATIVE'` text for live captions.
+
+## Available voices
+
+Nova 2 Sonic ships voices in ten locales. Tiffany and Matthew are polyglot and can speak any supported language.
+
+| Voice ID   | Name     | Language   | Locale | Gender    | Polyglot |
+| ---------- | -------- | ---------- | ------ | --------- | -------- |
+| `tiffany`  | Tiffany  | English    | en-US  | feminine  | yes      |
+| `matthew`  | Matthew  | English    | en-US  | masculine | yes      |
+| `amy`      | Amy      | English    | en-GB  | feminine  | no       |
+| `olivia`   | Olivia   | English    | en-AU  | feminine  | no       |
+| `kiara`    | Kiara    | English    | en-IN  | feminine  | no       |
+| `arjun`    | Arjun    | English    | en-IN  | masculine | no       |
+| `ambre`    | Ambre    | French     | fr-FR  | feminine  | no       |
+| `florian`  | Florian  | French     | fr-FR  | masculine | no       |
+| `beatrice` | Beatrice | Italian    | it-IT  | feminine  | no       |
+| `lorenzo`  | Lorenzo  | Italian    | it-IT  | masculine | no       |
+| `tina`     | Tina     | German     | de-DE  | feminine  | no       |
+| `lennart`  | Lennart  | German     | de-DE  | masculine | no       |
+| `lupe`     | Lupe     | Spanish    | es-US  | feminine  | no       |
+| `carlos`   | Carlos   | Spanish    | es-US  | masculine | no       |
+| `carolina` | Carolina | Portuguese | pt-BR  | feminine  | no       |
+| `leo`      | Leo      | Portuguese | pt-BR  | masculine | no       |
+| `kiara`    | Kiara    | Hindi      | hi-IN  | feminine  | no       |
+| `arjun`    | Arjun    | Hindi      | hi-IN  | masculine | no       |
+
+## Notes
+
+- Audio is streamed as 16-bit PCM. Assistant audio is emitted as `Int16Array` on the `speaking` event.
+- The voice instance must call `connect()` before any other streaming method.
+- `close()` destroys the underlying `BedrockRuntimeClient` to release the HTTP/2 session.
+- Nova 2 Sonic is available in `us-east-1`, `us-west-2`, and `ap-northeast-1`. Other regions throw a configuration error during construction.

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

@@ -37,7 +37,7 @@ const workspace = new Workspace({
 
 **vectorStore** (`MastraVector`): Vector store for semantic search
 
-**embedder** (`(text: string) => Promise<number[]>`): Embedder function for generating vectors. Required when vectorStore is provided.
+**embedder** (`Embedder`): Function that turns text into vectors. Required when \`vectorStore\` is set. Accepts either a single-text function \`(text: string) => Promise\<number\[]>\` or a batch-capable function \`(texts: string\[]) => Promise\<number\[]\[]>\` that has a \`batch: true\` property and an optional \`maxBatchSize\`. See \[Batch embedding]\(/docs/workspace/search#batch-embedding).
 
 **autoIndexPaths** (`string[]`): Paths or glob patterns to auto-index on init(). Supports glob patterns like '\*\*/\*.md' for selective indexing.
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.32-alpha.6
+
+### Patch Changes
+
+- Updated dependencies:
+  - @mastra/core@1.31.0-alpha.5
+
+## 1.1.32-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006), [`04151c7`](https://github.com/mastra-ai/mastra/commit/04151c7dcea934b4fe9076708a23fac161195414), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006)]:
+  - @mastra/core@1.31.0-alpha.4
+
 ## 1.1.32-alpha.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.32-alpha.4",
+  "version": "1.1.32-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.31.0-alpha.3",
-    "@mastra/mcp": "^1.6.0"
+    "@mastra/mcp": "^1.6.0",
+    "@mastra/core": "1.31.0-alpha.5"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
+    "@mastra/core": "1.31.0-alpha.5",
     "@internal/lint": "0.0.89",
-    "@internal/types-builder": "0.0.64",
-    "@mastra/core": "1.31.0-alpha.3"
+    "@internal/types-builder": "0.0.64"
   },
   "homepage": "https://mastra.ai",
   "repository": {