@mastra/mcp-docs-server 1.1.42-alpha.4 → 1.1.42-alpha.5

package/.docs/docs/observability/metrics/querying.md

@@ -0,0 +1,292 @@
+# Querying metrics
+
+Mastra exposes the same five OLAP queries (`getMetricAggregate`, `getMetricBreakdown`, `getMetricTimeSeries`, `getMetricPercentiles`, and discovery helpers) through three surfaces: an in-process store accessor, the runtime HTTP API, and the `mastra api metric` CLI. All three accept the same Zod-validated input shapes, so you can move from a one-off CLI investigation to a programmatic dashboard tool without re-learning the API.
+
+## When to use this
+
+- Build a custom dashboard or KPI tile alongside Studio.
+- Power a scheduled alert that fires when token cost or latency crosses a threshold.
+- Give an agent a tool that reads its own performance metrics and explains them in chat.
+- Run one-off investigations from a terminal with `mastra api metric ...`.
+
+For setup of the observability store itself, see the [Metrics overview](https://mastra.ai/docs/observability/metrics/overview). For the list of metric names you can query, see the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics).
+
+> **Note:** Metric queries are served by the observability domain, which requires an OLAP-capable store (DuckDB locally, ClickHouse in production). See [Metrics overview](https://mastra.ai/docs/observability/metrics/overview) for setup. If the observability store is not configured, `getStore('observability')` returns `null`.
+
+## Surfaces
+
+### In-process
+
+Inside a tool, server route, or workflow step, get the observability store from the Mastra storage:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const agentLatencyTool = createTool({
+  id: 'agentLatency',
+  description: 'Average agent latency over the last hour.',
+  inputSchema: z.object({}),
+  execute: async (_input, context) => {
+    const observability = await context.mastra!.getStorage()!.getStore('observability')
+    if (!observability) {
+      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
+    }
+
+    const result = await observability.getMetricAggregate({
+      name: ['mastra_agent_duration_ms'],
+      aggregation: 'avg',
+      filters: {
+        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
+      },
+    })
+
+    return { averageMs: result.value }
+  },
+})
+```
+
+`getStore('observability')` returns `null` when the configured backend does not support OLAP queries.
+
+### HTTP
+
+The `mastra dev` server (and any deployed Mastra runtime) exposes the same queries under `/api/observability/metrics/*`. Aggregate, breakdown, time series, and percentile endpoints take a JSON body with `POST`. Discovery endpoints use `GET` with query parameters.
+
+```bash
+curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
+  -H "content-type: application/json" \
+  -d '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}'
+```
+
+Available routes:
+
+- `POST /api/observability/metrics/aggregate`
+- `POST /api/observability/metrics/breakdown`
+- `POST /api/observability/metrics/timeseries`
+- `POST /api/observability/metrics/percentiles`
+- `GET /api/observability/metrics` (raw rows, paginated)
+- `GET /api/observability/discovery/metric-names`
+- `GET /api/observability/discovery/metric-label-keys`
+- `GET /api/observability/discovery/metric-label-values`
+
+The `@mastra/client-js` SDK wraps the same routes as `mastraClient.getMetricAggregate(...)`, `getMetricBreakdown(...)`, and so on.
+
+### CLI
+
+`mastra api metric ...` calls the same endpoints with a single JSON argument, so an agent or shell script can fetch metrics without writing any code:
+
+```bash
+mastra api metric aggregate \
+  '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
+  --url http://localhost:4111 --pretty
+```
+
+By default the CLI targets hosted Mastra observability (`https://observability.mastra.ai`). Pass `--url http://localhost:4111` to query a local `mastra dev` server. See [`mastra api metric aggregate`](https://mastra.ai/reference/cli/mastra) and the surrounding entries for the full command list.
+
+## Queries
+
+### `getMetricAggregate`
+
+Returns a single scalar — the building block for KPI cards.
+
+Inputs:
+
+- `name`: Array of one or more metric names.
+- `aggregation`: One of `'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'`.
+- `filters`: Optional [filter object](#filtering).
+- `comparePeriod`: Optional `'previous_period' | 'previous_day' | 'previous_week'` for period-over-period comparison.
+
+Response:
+
+- `value`, `previousValue`, `changePercent`.
+- `estimatedCost`, `costUnit`, `previousEstimatedCost`, `costChangePercent` for token metrics.
+
+```typescript
+const observability = await mastra.getStorage()!.getStore('observability')
+
+const cost = await observability!.getMetricAggregate({
+  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
+  aggregation: 'sum',
+  comparePeriod: 'previous_day',
+})
+
+console.log(cost.value, cost.estimatedCost, cost.costUnit, cost.changePercent)
+```
+
+### `getMetricBreakdown`
+
+Groups rows by one or more dimensions and aggregates each group — the building block for top-N tables (e.g. "tokens by agent").
+
+Inputs:
+
+- `name`: Array of metric names.
+- `groupBy`: Array of fields to group by (for example `['entityName']`).
+- `aggregation`: Same enum as above.
+- `limit`: Server-side top-K cap. Required for high-cardinality `groupBy`.
+- `orderDirection`: `'ASC' | 'DESC'` (defaults to `DESC`).
+- `filters`: Optional.
+
+Response: `groups[]`, each with `dimensions` (record of group keys to values), `value`, and `estimatedCost`.
+
+```typescript
+const byAgent = await observability!.getMetricBreakdown({
+  name: ['mastra_model_total_input_tokens'],
+  groupBy: ['entityName'],
+  aggregation: 'sum',
+  limit: 10,
+  orderDirection: 'DESC',
+})
+```
+
+### `getMetricTimeSeries`
+
+Buckets values by a fixed interval — the building block for line and bar charts.
+
+Inputs:
+
+- `name`: Array of metric names.
+- `interval`: One of `'1m' | '5m' | '15m' | '1h' | '1d'`.
+- `aggregation`: Same enum.
+- `groupBy`: Optional. When omitted, multiple metric names are summed into one series; use one call per metric to keep them separate.
+- `filters`: Optional.
+
+Response: `series[]`, each with `name`, `costUnit`, and `points[]` of `{ timestamp, value, estimatedCost }`.
+
+```typescript
+const inputTokens = await observability!.getMetricTimeSeries({
+  name: ['mastra_model_total_input_tokens'],
+  aggregation: 'sum',
+  interval: '1h',
+  filters: {
+    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+  },
+})
+```
+
+### `getMetricPercentiles`
+
+Returns percentile values bucketed by time — the building block for latency charts.
+
+Inputs:
+
+- `name`: Single metric name (string, not array).
+- `percentiles`: Array of numbers between `0` and `1`, for example `[0.5, 0.95, 0.99]`.
+- `interval`: Same enum as `getMetricTimeSeries`.
+- `filters`: Optional.
+
+Response: `series[]`, each with `percentile` and `points[]` of `{ timestamp, value }`.
+
+```typescript
+const latency = await observability!.getMetricPercentiles({
+  name: 'mastra_agent_duration_ms',
+  percentiles: [0.5, 0.95],
+  interval: '1h',
+})
+```
+
+### Discovery
+
+Use these endpoints to populate dropdowns or to give an agent the menu of values it can filter by. All discovery routes are `GET` and live under `/api/observability/discovery/`.
+
+**Metric-specific** (also exposed as `mastra api metric` subcommands):
+
+| Method                 | Args                                        | Path suffix           | CLI                              |
+| ---------------------- | ------------------------------------------- | --------------------- | -------------------------------- |
+| `getMetricNames`       | `{ prefix?, limit? }`                       | `metric-names`        | `mastra api metric names`        |
+| `getMetricLabelKeys`   | `{ metricName }`                            | `metric-label-keys`   | `mastra api metric label-keys`   |
+| `getMetricLabelValues` | `{ metricName, labelKey, prefix?, limit? }` | `metric-label-values` | `mastra api metric label-values` |
+
+**Shared with traces and logs** (HTTP-only, no dedicated CLI subcommand):
+
+| Method            | Args              | Path suffix     |
+| ----------------- | ----------------- | --------------- |
+| `getEntityTypes`  | `{}`              | `entity-types`  |
+| `getEntityNames`  | `{ entityType? }` | `entity-names`  |
+| `getServiceNames` | `{}`              | `service-names` |
+| `getEnvironments` | `{}`              | `environments`  |
+| `getTags`         | `{ entityType? }` | `tags`          |
+
+## Filtering
+
+Every query accepts the same `filters` object. The most useful fields:
+
+- `name`: Restrict to specific metric names. (Top-level `name` already does this for aggregate/breakdown/timeseries; use `filters.name` when you want to mix multiple metrics under a single query.)
+- `timestamp`: `{ start, end, startExclusive, endExclusive }`. Both bounds are optional; omit `end` for "until now".
+- `provider`, `model`, `costUnit`: For token and cost metrics.
+- `labels`: Exact key-value match on metric labels, for example `{ status: 'error' }` for duration metrics.
+- Correlation fields: `entityType`, `entityName`, `parentEntityName`, `rootEntityName`, `userId`, `organizationId`, `resourceId`, `runId`, `sessionId`, `threadId`, `requestId`, `executionSource`, `environment`, `serviceName`, `experimentId`, `tags`.
+
+The same `filters` shape works across all three surfaces:
+
+```typescript
+// In-process
+await observability!.getMetricAggregate({
+  name: ['mastra_tool_duration_ms'],
+  aggregation: 'avg',
+  filters: { entityName: 'weatherTool', labels: { status: 'error' } },
+})
+```
+
+```bash
+# CLI
+mastra api metric aggregate \
+  '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}' \
+  --url http://localhost:4111
+```
+
+```bash
+# HTTP
+curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
+  -H "content-type: application/json" \
+  -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'
+```
+
+## Example: build a custom KPI tile
+
+The following tool returns input-token volume and estimated cost for the last hour. An agent or a dashboard can call it as `structuredContent` without re-implementing the query.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const tokenKpiTool = createTool({
+  id: 'tokenKpi',
+  description: 'Returns input-token volume and estimated cost for the last hour.',
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    inputTokens: z.number().nullable(),
+    estimatedCost: z.number().nullable(),
+    costUnit: z.string().nullable(),
+    changePercent: z.number().nullable(),
+  }),
+  execute: async (_input, context) => {
+    const observability = await context.mastra!.getStorage()!.getStore('observability')
+    if (!observability) {
+      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
+    }
+
+    const result = await observability.getMetricAggregate({
+      name: ['mastra_model_total_input_tokens'],
+      aggregation: 'sum',
+      filters: {
+        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
+      },
+      comparePeriod: 'previous_period',
+    })
+
+    return {
+      inputTokens: result.value,
+      estimatedCost: result.estimatedCost ?? null,
+      costUnit: result.costUnit ?? null,
+      changePercent: result.changePercent ?? null,
+    }
+  },
+})
+```
+
+## Related
+
+- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
+- [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
+- [CLI: `mastra api metric ...`](https://mastra.ai/reference/cli/mastra)
+- [Studio observability](https://mastra.ai/docs/studio/observability)

package/.docs/docs/server/auth/fga.md

@@ -1,5 +1,7 @@
 # Fine-Grained Authorization (FGA)
 
+> **Note:** Fine-Grained Authorization is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
 Fine-Grained Authorization (FGA) adds resource-level permission checks to your Mastra application. While RBAC answers "can this role do this action?", FGA answers **"can this user do this action on this specific resource?"**
 
 ## When to use FGA

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

@@ -686,6 +686,48 @@ 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.
 
+**Inworld Realtime**:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+import { InworldRealtimeVoice } from '@mastra/voice-inworld'
+
+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 InworldRealtimeVoice({
+    apiKey: process.env.INWORLD_API_KEY,
+    model: 'inworld/models/gemma-4-26b-a4b-it',
+    speaker: 'Sarah',
+  }),
+})
+
+// Connect before using speak/send
+await voiceAgent.voice.connect()
+
+// Listen for agent audio (PCM stream)
+voiceAgent.voice.on('speaker', stream => {
+  playAudio(stream)
+})
+
+// Listen for text responses and transcriptions
+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 [Inworld Realtime Reference](https://mastra.ai/reference/voice/inworld-realtime) for more information on the Inworld Realtime voice provider.
+
 **xAI**:
 
 ```typescript
@@ -1051,6 +1093,26 @@ const voice = new NovaSonicVoice({
 
 Visit the [AWS Nova Sonic Reference](https://mastra.ai/reference/voice/aws-nova-sonic) for more information on the AWS Nova Sonic voice provider.
 
+**Inworld Realtime**:
+
+```typescript
+// Inworld Realtime Voice Configuration
+const voice = new InworldRealtimeVoice({
+  apiKey: process.env.INWORLD_API_KEY,
+  model: 'inworld/models/gemma-4-26b-a4b-it',
+  speaker: 'Sarah',
+  // Typed Inworld realtime knobs (semantic VAD, playback speed, MCP tool routing, ...)
+  session: {
+    audio: {
+      output: { speed: 1.1 },
+      input: { turn_detection: { type: 'semantic_vad', eagerness: 'high' } },
+    },
+  },
+})
+```
+
+Visit the [Inworld Realtime Reference](https://mastra.ai/reference/voice/inworld-realtime) for more information on the Inworld Realtime voice provider.
+
 **AI SDK**:
 
 ```typescript

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

@@ -143,4 +143,55 @@ 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`.
+- Events: `speaking` (Int16Array audio), `writing` (text with `generationStage`), `toolCall`, `interrupt`, `turnComplete`, `usage`, `session`, and `error`.
+
+## Inworld Realtime
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InworldRealtimeVoice } from '@mastra/voice-inworld'
+import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
+
+const agent = new Agent({
+  id: 'agent',
+  name: 'Inworld Realtime 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 InworldRealtimeVoice({
+    apiKey: process.env.INWORLD_API_KEY,
+    model: 'inworld/models/gemma-4-26b-a4b-it',
+    speaker: 'Sarah',
+    // Typed Inworld realtime knobs (semantic VAD, playback speed, etc.)
+    // session: {
+    //   audio: {
+    //     output: { speed: 1.1 },
+    //     input: { turn_detection: { type: 'semantic_vad', eagerness: 'high' } },
+    //   },
+    // },
+  }),
+})
+
+await agent.voice.connect()
+
+agent.voice.on('speaker', stream => {
+  playAudio(stream)
+})
+
+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:
+
+- Requires `INWORLD_API_KEY`. Inworld API keys ship pre-Basic-encoded — paste them verbatim.
+- The WebSocket URL appends a client-generated `?key=...&protocol=realtime`. The model is configured via the initial `session.update`, not in the URL.
+- Inworld's wire protocol is the OpenAI Realtime GA spec, so event names match `@mastra/voice-openai-realtime`.
+- Typed Inworld realtime knobs (MCP tool routing, semantic VAD eagerness, playback speed, transcription model, output modalities, …) are exposed through the `session` constructor field; an untyped `providerData` escape hatch is also deep-merged for forward compatibility with new Inworld features.
+- Events: `speaker` (PCM audio stream), `speaking` (audio Buffer per delta), `writing` (text), `conversation.item.added`, `conversation.item.done`, `function_call.arguments`, `tool-call-start`, `tool-call-result`, and `error`.

package/.docs/docs/workspace/sandbox.md

@@ -16,6 +16,7 @@ A sandbox provider executes commands in a controlled environment:
 ## Supported providers
 
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox): Executes commands on the local machine
+- [`AgentCoreRuntimeSandbox`](https://mastra.ai/reference/workspace/agentcore-runtime-sandbox): Executes commands in AWS Bedrock AgentCore Runtime sessions
 - [`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox): Executes commands in isolated Blaxel cloud sandboxes
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
@@ -118,9 +119,10 @@ Use `null` or `false` for cloud sandboxes (for example, E2B, Daytona, or Modal)
 ## Related
 
 - [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager)
-- [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
-- [`ModalSandbox` reference](https://mastra.ai/reference/workspace/modal-sandbox)
+- [`AgentCoreRuntimeSandbox` reference](https://mastra.ai/reference/workspace/agentcore-runtime-sandbox)
 - [`DaytonaSandbox` reference](https://mastra.ai/reference/workspace/daytona-sandbox)
 - [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [`ModalSandbox` reference](https://mastra.ai/reference/workspace/modal-sandbox)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)

package/.docs/guides/guide/firecrawl.md

@@ -16,25 +16,25 @@ Install the Firecrawl SDK:
 **npm**:
 
 ```bash
-npm install @mendable/firecrawl-js
+npm install firecrawl
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mendable/firecrawl-js
+pnpm add firecrawl
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mendable/firecrawl-js
+yarn add firecrawl
 ```
 
 **Bun**:
 
 ```bash
-bun add @mendable/firecrawl-js
+bun add firecrawl
 ```
 
 ## Configure environment variables
@@ -53,7 +53,7 @@ Create a tool file that exposes Firecrawl search and scrape to Mastra.
 1. Create `src/mastra/tools/firecrawl.ts` and set up Firecrawl:
 
    ```ts
-   import Firecrawl from '@mendable/firecrawl-js'
+   import { Firecrawl } from 'firecrawl'
    import { createTool } from '@mastra/core/tools'
    import { z } from 'zod'
 

package/.docs/models/embeddings.md

@@ -40,12 +40,12 @@ const embedder = new ModelRouterEmbeddingModel("google/gemini-embedding-001");
 The model router automatically detects API keys from environment variables:
 
 - **OpenAI**: `OPENAI_API_KEY`
-- **Google**: `GOOGLE_GENERATIVE_AI_API_KEY`
+- **Google**: `GOOGLE_API_KEY` (falls back to `GOOGLE_GENERATIVE_AI_API_KEY`)
 
 ```bash
 # .env
 OPENAI_API_KEY=sk-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
+GOOGLE_API_KEY=...
 ```
 
 ## Custom Providers

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

@@ -96,9 +96,9 @@ export const agent = new Agent({
 
 ## Thread signals
 
-Use Agent signals to send real-time context into a memory thread. Signals are useful when a user adds input while an agent is already streaming, or when another process needs to add structured context to the thread.
+Use Agent signals to send real-time input and context into a memory thread. Message APIs are for user-authored input. `sendSignal()` is the lower-level API for system-generated context.
 
-A `user-message` signal represents user input. When the target thread is running, Mastra delivers the signal into the active agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input by default.
+When the target thread is running, `sendMessage()` delivers the message into the active agent loop. When the thread is idle, Mastra starts a stream with the message as the first input by default.
 
 ```typescript
 const subscription = await agent.subscribeToThread({
@@ -112,26 +112,22 @@ void (async () => {
   }
 })()
 
-agent.sendSignal(
-  { type: 'user-message', contents: 'Use the latest customer note too.' },
-  {
-    resourceId: 'user-123',
-    threadId: 'thread-abc',
-    ifIdle: {
-      streamOptions: {
-        maxSteps: 3,
-      },
+agent.sendMessage('Use the latest customer note too.', {
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    streamOptions: {
+      maxSteps: 3,
     },
   },
-)
+})
 ```
 
-Use `attributes` to identify different users in a shared thread. The signal type and attributes are rendered as XML so the model can distinguish who said what:
+Use `attributes` to identify different users in a shared thread. The attributes are rendered as XML so the model can distinguish who said what:
 
 ```typescript
-agent.sendSignal(
+agent.sendMessage(
   {
-    type: 'user',
     contents: 'Can we simplify the API surface?',
     attributes: { name: 'Devin', from: 'slack' },
   },
@@ -147,11 +143,44 @@ The model receives this as:
 
 The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
 
+### `sendMessage(message, options)`
+
+Sends a user message to an active run or memory thread. Use this when the active agent should receive the message immediately.
+
+**message** (`string | Array<TextPart | FilePart> | { contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): User-authored input. Bare strings and parts without attributes are sent to the model as normal user input. When \`attributes\` are present, Mastra renders the message as a \`\<user>\` XML element with the attributes included.
+
+**options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
+
+**options.resourceId** (`string`): Resource ID for the memory thread. Required with \`threadId\` for thread-targeted messages.
+
+**options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted messages.
+
+**options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`. Mastra uses the top-level \`resourceId\` and \`threadId\` for memory context.
+
+Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory.
+
+### `queueMessage(message, options)`
+
+Queues a user message for the next turn on a thread. If the thread is active, Mastra waits for the active run to finish, then starts a new run with the queued message. If the thread is idle, Mastra starts a run immediately.
+
+```typescript
+agent.queueMessage('Also check whether the tests need updates.', {
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+```
+
+`queueMessage()` accepts the same `message` and `options` shape as `sendMessage()` and returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`.
+
 ### `sendSignal(signal, options)`
 
 Sends a signal to an active run or memory thread.
 
-**signal** (`{ type: 'user-message' | 'system-reminder' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals without attributes are treated as plain user input. All other signals — including \`user-message\` with \`attributes\`, \`system-reminder\`, and custom types — are wrapped in an XML element named after the signal type with \`attributes\` rendered as XML attributes (e.g. \`\<user name="Devin" from="slack">message\</user>\`). The model sees the XML; the UI sees the raw contents and can read \`attributes\` for custom rendering. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
+**signal** (`{ type: 'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Signal context to send to the thread. \`type\` is the semantic signal category. \`tagName\` controls the XML tag the model sees. For example, \`{ type: 'notification', tagName: 'github-review' }\` renders as \`\<github-review>...\</github-review>\`. Legacy \`user-message\` and \`system-reminder\` payloads are still accepted and normalized. Unknown \`type\` values are rejected; use \`tagName\` for custom XML tags.
 
 **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
 
@@ -169,7 +198,7 @@ Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?
 
 ### `subscribeToThread(options)`
 
-Subscribes to raw stream chunks for a memory thread. Use this before calling `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
+Subscribes to raw stream chunks for a memory thread. Use this before calling `sendMessage()`, `queueMessage()`, or `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
 
 **options.resourceId** (`string`): Resource ID for the memory thread.
 

package/.docs/reference/index.md

@@ -274,6 +274,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Google](https://mastra.ai/reference/voice/google)
 - [Google Gemini Live](https://mastra.ai/reference/voice/google-gemini-live)
 - [Inworld](https://mastra.ai/reference/voice/inworld)
+- [Inworld Realtime](https://mastra.ai/reference/voice/inworld-realtime)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)
@@ -315,6 +316,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.start()](https://mastra.ai/reference/workflows/run-methods/start)
 - [.startAsync()](https://mastra.ai/reference/workflows/run-methods/startAsync)
 - [.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
+- [AgentCoreRuntimeSandbox](https://mastra.ai/reference/workspace/agentcore-runtime-sandbox)
 - [AgentFSFilesystem](https://mastra.ai/reference/workspace/agentfs-filesystem)
 - [AzureBlobFilesystem](https://mastra.ai/reference/workspace/azure-blob-filesystem)
 - [BlaxelSandbox](https://mastra.ai/reference/workspace/blaxel-sandbox)
@@ -329,6 +331,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)
+- [VercelMicroVMSandbox](https://mastra.ai/reference/workspace/vercel-microvm-sandbox)
 - [VercelSandbox](https://mastra.ai/reference/workspace/vercel)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
 - [WorkspaceFilesystem](https://mastra.ai/reference/workspace/filesystem)

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -127,4 +127,10 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### Token metrics are missing
 
 - **Span is a model generation**: Token metrics are only emitted from `MODEL_GENERATION` spans.
-- **Provider reports usage**: The model provider must include `usage` data in its response. If usage is absent, no token metrics are emitted.
+- **Provider reports usage**: The model provider must include `usage` data in its response. If usage is absent, no token metrics are emitted.
+
+## Related
+
+- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
+- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
+- [Studio observability](https://mastra.ai/docs/studio/observability)