@mastra/mcp-docs-server 1.2.15-alpha.3 → 1.2.15-alpha.6

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

@@ -36,7 +36,7 @@ for await (const chunk of stream) {
 
 | Model                           | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `opencode-go/deepseek-v4-flash` | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `opencode-go/deepseek-v4-flash` | 1.0M    |       |           |       |       |       | $0.07      | $0.14       |
 | `opencode-go/deepseek-v4-pro`   | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `opencode-go/glm-5.1`           | 203K    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/glm-5.2`           | 1.0M    |       |           |       |       |       | $1         | $4          |

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

@@ -2,7 +2,7 @@
 
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 86 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 87 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -86,7 +86,7 @@ for await (const chunk of stream) {
 | `opencode/kimi-k2.7-code`         | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `opencode/kimi-k3`                | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `opencode/laguna-s-2.1-free`      | 256K    |       |           |       |       |       | —          | —           |
-| `opencode/ling-3.0-flash-free`    | 262K    |       |           |       |       |       | —          | —           |
+| `opencode/ling-3.0-tiny-free`     | 262K    |       |           |       |       |       | —          | —           |
 | `opencode/longcat-2.0-free`       | 1.0M    |       |           |       |       |       | —          | —           |
 | `opencode/mimo-v2.5-free`         | 200K    |       |           |       |       |       | —          | —           |
 | `opencode/minimax-m2.5`           | 205K    |       |           |       |       |       | $0.30      | $1          |

package/.docs/models/providers/vivgrid.md

@@ -2,7 +2,7 @@
 
 # ![Vivgrid logo](https://models.dev/logos/vivgrid.svg)Vivgrid
 
-Access 17 Vivgrid models through Mastra's model router. Authentication is handled automatically using the `VIVGRID_API_KEY` environment variable.
+Access 19 Vivgrid models through Mastra's model router. Authentication is handled automatically using the `VIVGRID_API_KEY` environment variable.
 
 Learn more in the [Vivgrid documentation](https://docs.vivgrid.com/models).
 
@@ -37,6 +37,7 @@ for await (const chunk of stream) {
 | Model                                   | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | --------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `vivgrid/deepseek-v3.2`                 | 128K    |       |           |       |       |       | $0.28      | $0.42       |
+| `vivgrid/deepseek-v4-flash`             | 1.0M    |       |           |       |       |       | $0.15      | $0.30       |
 | `vivgrid/deepseek-v4-pro`               | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `vivgrid/gemini-3.1-flash-lite-preview` | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `vivgrid/gemini-3.1-pro-preview`        | 1.0M    |       |           |       |       |       | $2         | $12         |
@@ -53,6 +54,7 @@ for await (const chunk of stream) {
 | `vivgrid/gpt-5.6-luna`                  | 1.1M    |       |           |       |       |       | $1         | $6          |
 | `vivgrid/gpt-5.6-sol`                   | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `vivgrid/gpt-5.6-terra`                 | 1.1M    |       |           |       |       |       | $3         | $15         |
+| `vivgrid/kimi-k3`                       | 1.0M    |       |           |       |       |       | $3         | $15         |
 
 ## Advanced configuration
 
@@ -82,7 +84,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "vivgrid/gpt-5.6-terra"
+      ? "vivgrid/kimi-k3"
       : "vivgrid/deepseek-v3.2";
   }
 });

package/.docs/models/providers/wandb.md

@@ -39,7 +39,7 @@ for await (const chunk of stream) {
 | `wandb/deepseek-ai/DeepSeek-V3.1`                    | 161K    |       |           |       |       |       | $0.55      | $2          |
 | `wandb/deepseek-ai/DeepSeek-V4-Flash`                | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `wandb/deepseek-ai/DeepSeek-V4-Flash-0731`           | 262K    |       |           |       |       |       | $0.13      | $0.28       |
-| `wandb/deepseek-ai/DeepSeek-V4-Pro`                  | 1.0M    |       |           |       |       |       | $2         | $3          |
+| `wandb/deepseek-ai/DeepSeek-V4-Pro`                  | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `wandb/google/gemma-4-31B-it`                        | 262K    |       |           |       |       |       | $0.10      | $0.34       |
 | `wandb/ibm-granite/granite-4.1-8b`                   | 131K    |       |           |       |       |       | $0.05      | $0.10       |
 | `wandb/JetBrains/Mellum2-12B-A2.5B-Instruct`         | 131K    |       |           |       |       |       | $0.05      | $0.10       |

package/.docs/reference/agents/channels.md

@@ -102,7 +102,7 @@ const agent = new Agent({
 
 **streaming** (`boolean | { updateIntervalMs?: number }`): Stream agent text deltas to the channel as the agent generates them instead of buffering and posting once per step. Requires the underlying adapter to support post-and-edit streaming. Slack defaults to true; other adapters default to false. (Default: `false (true for Slack)`)
 
-**toolDisplay** (`'cards' | 'text' | 'timeline' | 'grouped' | 'hidden' | ToolDisplayFn`): How tool calls are rendered in the channel. "cards" posts per-tool running/result cards as rich Block Kit. "text" posts the same lifecycle as plain text (no Block Kit). "timeline" and "grouped" stream tool state as inline task\_update chunks (requires streaming: true; Slack only today — other adapters may render a placeholder). "hidden" executes tools silently. Pass a function to render tool events yourself; return { kind: "post", message } for a discrete post/edit, { kind: "stream", chunk } to push into the active streaming widget, or undefined to skip rendering that event. Approve/deny prompts always render as a separate card regardless of mode. (Default: `'cards' ('grouped' for Slack)`)
+**toolDisplay** (`'cards' | 'text' | 'timeline' | 'grouped' | 'hidden' | ToolDisplayFn`): How tool calls are rendered in the channel. "cards" posts per-tool running/result cards as rich Block Kit. "text" posts the same lifecycle as plain text (no Block Kit). "timeline" and "grouped" stream tool state as inline task\_update chunks (requires streaming: true; Slack only today — other adapters may render a placeholder). "hidden" executes tools silently. Pass a function to render tool events yourself; return { kind: "post", message } for a discrete post/edit, { kind: "stream", chunk } to push into the streaming widget, or undefined to skip rendering that event. Add openIfEmpty: false to a stream result when its chunk should only apply to an active streaming session. Approve/deny prompts always render as a separate card regardless of mode. (Default: `'cards' ('grouped' for Slack)`)
 
 **typingStatus** (`boolean | ((chunk: AgentChunkType, ctx: TypingStatusContext) => string | false | null | undefined | void)`): Control the platform typing indicator. true uses built-in defaults (is typing… on text, is calling {tool}… on tool-call, is waiting for approval… on tool-call-approval). false suppresses typing entirely — useful when a live streaming widget (e.g. toolDisplay: "grouped" in Slack) already conveys progress. Pass a function to set custom status copy per chunk; return a string to set the status, or false/null/undefined to leave it unchanged. Compose with defaultTypingStatus (exported from @mastra/core/channels) to fall back to defaults for chunks you don't handle. (Default: `true`)
 
@@ -116,6 +116,25 @@ const agent = new Agent({
 
 Pass a function to `toolDisplay` for fully custom rendering. The function receives a `ToolDisplayEvent` (`running` / `result` / `error` / `approval`) and a `ToolDisplayContext` (`{ mode, platform }`); return `{ kind: 'post', message }` for a discrete post/edit, `{ kind: 'stream', chunk }` to push into the active streaming widget, or `undefined` to skip rendering that event.
 
+By default, a stream result opens a streaming session when none is active. Set `openIfEmpty: false` when the chunk only applies to an existing session. Mastra skips the chunk when no session is active. Static channels ignore this option and keep their existing plain-text fallback behavior.
+
+```typescript
+toolDisplay: event => {
+  if (event.kind !== 'running') return undefined
+
+  return {
+    kind: 'stream',
+    chunk: {
+      type: 'task_update',
+      id: event.toolCallId,
+      title: event.displayName,
+      status: 'in_progress',
+    },
+    openIfEmpty: false,
+  }
+}
+```
+
 Approve/deny prompts (`requireApproval`) always render as a separate card regardless of mode, because inline task entries can't carry interactive buttons.
 
 ```typescript

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

@@ -12,6 +12,19 @@ Retrieve a list of all available workflows:
 const workflows = await mastraClient.listWorkflows()
 ```
 
+## Getting workflow run counts
+
+Retrieve per-workflow counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs in a single request. The counts are computed on the server and keyed by the workflow's registry key — the key used when registering the workflow in the Mastra config, which can differ from the workflow's own `id`:
+
+```typescript
+const runCounts = await mastraClient.listWorkflowRunCounts()
+// { "cityWorkflow": { running: 2, suspended: 1 }, ... }
+```
+
+Returns: `Record<string, { running: number; suspended: number }>`
+
+The server may cache the counts for a few seconds between requests. Servers that predate this endpoint respond with `404 Not Found` — handle the error when the client can talk to older deployments.
+
 ## Working with a specific workflow
 
 Get an instance of a specific workflow by its ID:

package/.docs/reference/file-based-agents/config.md

@@ -69,32 +69,33 @@ Please note:
 
 Keep `config.ts` focused on runtime options. Use sibling files for concerns that benefit from their own location.
 
-| Setting      | File or folder                                                                  | Why it lives there                                                   |
-| ------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Instructions | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Keeps the always-on prompt readable as markdown                      |
-| Tools        | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Gives each callable action its own typed module                      |
-| Skills       | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Keeps load-on-demand procedures separate from always-on instructions |
-| Memory       | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | Configures persistent memory without crowding runtime options        |
-| Workspace    | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | Configures files and sandbox behavior separately from model settings |
-| Processors   | [`processors/`](https://mastra.ai/reference/file-based-agents/processors)       | Separates input and output processing pipelines                      |
-| Subagents    | [`subagents/`](https://mastra.ai/reference/file-based-agents/subagents)         | Gives each specialist child agent its own directory                  |
+| Setting      | File or folder                                                                                       | Why it lives there                                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Instructions | [`instructions.md` or `instructions.ts`](https://mastra.ai/reference/file-based-agents/instructions) | Keeps the always-on prompt readable as markdown, or computed in TypeScript |
+| Tools        | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                                      | Gives each callable action its own typed module                            |
+| Skills       | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)                                    | Keeps load-on-demand procedures separate from always-on instructions       |
+| Memory       | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)                                  | Configures persistent memory without crowding runtime options              |
+| Workspace    | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)                            | Configures files and sandbox behavior separately from model settings       |
+| Processors   | [`processors/`](https://mastra.ai/reference/file-based-agents/processors)                            | Separates input and output processing pipelines                            |
+| Subagents    | [`subagents/`](https://mastra.ai/reference/file-based-agents/subagents)                              | Gives each specialist child agent its own directory                        |
 
 ## Precedence
 
 `config.ts` merges with the agent's other files according to these rules:
 
-| Domain       | Source A                      | Source B                                                                        | Winner                                                  |
-| ------------ | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| Instructions | Dynamic `config.instructions` | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Dynamic `config.instructions`                           |
-| Instructions | Static `config.instructions`  | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | `instructions.md`                                       |
-| Tools        | `config.tools`                | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Both merge; `config.tools` wins on key collisions       |
-| Tools        | Function `config.tools`       | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Function `config.tools`; discovered tools are ignored   |
-| Skills       | `config.skills`               | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Both merge; `config.skills` wins on name collisions     |
-| Skills       | Function `config.skills`      | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Function `config.skills`; discovered skills are ignored |
-| Memory       | `config.memory`               | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | `config.memory`                                         |
-| Workspace    | `config.workspace`            | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | `config.workspace`                                      |
-
-Missing both `instructions.md` and `config.instructions` fails the build. Missing both `config.memory` and `memory.ts` leaves the agent without memory.
+| Domain       | Source A                                                                        | Source B                                                                                             | Winner                                                  |
+| ------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Instructions | Dynamic `config.instructions`                                                   | [`instructions.ts` or `instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Dynamic `config.instructions`                           |
+| Instructions | Static `config.instructions`                                                    | [`instructions.ts` or `instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The instructions file                                   |
+| Instructions | [`instructions.ts`](https://mastra.ai/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions)                      | `instructions.ts`                                       |
+| Tools        | `config.tools`                                                                  | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                                      | Both merge; `config.tools` wins on key collisions       |
+| Tools        | Function `config.tools`                                                         | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                                      | Function `config.tools`; discovered tools are ignored   |
+| Skills       | `config.skills`                                                                 | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)                                    | Both merge; `config.skills` wins on name collisions     |
+| Skills       | Function `config.skills`                                                        | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)                                    | Function `config.skills`; discovered skills are ignored |
+| Memory       | `config.memory`                                                                 | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)                                  | `config.memory`                                         |
+| Workspace    | `config.workspace`                                                              | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)                            | `config.workspace`                                      |
+
+Missing `instructions.md`, `instructions.ts`, and `config.instructions` fails the build. Missing both `config.memory` and `memory.ts` leaves the agent without memory.
 
 ## Discovery lifecycle
 

package/.docs/reference/file-based-agents/instructions.md

@@ -2,9 +2,11 @@
 
 # Instructions
 
-An agent's `instructions.md` holds its always-on system prompt: the model reads it on every turn. Use it to define the agent's identity, tone, role, and standing rules.
+An agent's instructions hold its always-on system prompt: the model reads it on every turn. Use them to define the agent's identity, tone, role, and standing rules.
 
-Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented out of `instructions.md` and into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+Write them in one of two files at the agent root. Use `instructions.md` when the prompt is fixed text. Use `instructions.ts` when the prompt needs code, for example when it's built from shared constants or resolved per request.
+
+Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
 
 ## Quickstart
 
@@ -25,30 +27,53 @@ Effective instructions cover the parts of an agent's behavior that don't change
 
 Move conditional, large, or action-oriented guidance into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
 
-## Dynamic instructions
+## Instructions in TypeScript
+
+Use `instructions.ts` when markdown can't express the prompt. The file default-exports a string, a system message, or a function returning one, and `agentInstructions()` types the export without changing it.
+
+Export a string when the prompt is assembled in code, for example from constants shared with the rest of your app:
+
+```typescript
+import { agentInstructions } from '@mastra/core/agent'
+import { SUPPORTED_UNITS } from '../../constants'
+
+export default agentInstructions(`
+You are a helpful weather assistant.
+Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
+`)
+```
 
-When the prompt needs to change per request, for example based on the current user or runtime context, set a runtime-defined `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+Export a function when the prompt depends on the request. Mastra calls it on every turn and passes the request context:
 
 ```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.6-sol',
-  instructions: ({ runtimeContext }) => {
-    const tier = runtimeContext.get('tier') ?? 'standard'
-    return `You are a support agent. Treat this as a ${tier}-tier customer.`
-  },
+import { agentInstructions } from '@mastra/core/agent'
+
+export default agentInstructions(({ requestContext }) => {
+  const tier = requestContext.get('tier') ?? 'standard'
+  return `You are a support agent. Treat this as a ${tier}-tier customer.`
 })
 ```
 
+The function can be `async` and receives `mastra` alongside `requestContext`, so it can read from storage or another registered primitive before returning the prompt.
+
+Both files can also live in a [subagent](https://mastra.ai/reference/file-based-agents/subagents) directory, which follows the same rules.
+
 ## Build-time behavior
 
-Mastra reads `instructions.md` and inlines its contents into the generated code when the bundler builds your project. The deployed agent doesn't read the file at runtime, so changes to `instructions.md` take effect only after the next build.
+`instructions.md` and `instructions.ts` reach the deployed agent differently:
+
+- `instructions.md`: Mastra reads the file and inlines its contents into the generated code at build time.
+- `instructions.ts`: The generated code imports the module, so it's bundled like any other TypeScript file and can import from the rest of your project.
+
+Under `mastra dev`, editing either file triggers a rebuild. In a deployed app neither file is read from disk at runtime, so changes take effect after the next build.
 
 ## Precedence with config
 
-Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+Instructions can come from `instructions.ts`, `instructions.md`, or the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+
+- A runtime-defined (function) `instructions` in `config.ts` wins over both files.
+- Otherwise `instructions.ts` wins over `instructions.md`.
+- `instructions.md` wins over a static `instructions` string in `config.ts`.
+- If none is present, the build fails and names the agent directory.
 
-- A runtime-defined (function) `instructions` in `config.ts` wins over `instructions.md`.
-- Otherwise `instructions.md` wins over a static `instructions` string.
-- If neither is present, the build fails and names the agent directory.
+Defining instructions in more than one place logs a warning that names both sources and which one wins. Keep one source per agent.

package/.docs/reference/index.md

@@ -302,6 +302,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createBedrockKBTool()](https://mastra.ai/reference/tools/bedrock-kb-tool)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)

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

@@ -64,17 +64,19 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+
+A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
 ### What cost fields may be included
 
-| Field           | Description                                                                  |
-| --------------- | ---------------------------------------------------------------------------- |
-| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                   |
-| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                 |
-| `estimatedCost` | Estimated cost for this metric, calculated from token count and pricing tier |
-| `costUnit`      | Currency unit (e.g. `USD`)                                                   |
-| `costMetadata`  | Additional pricing context (tier information, error details)                 |
+| Field           | Description                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                                                         |
+| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                                                       |
+| `estimatedCost` | Estimated cost from token count and pricing tier, or a total reported by the provider                              |
+| `costUnit`      | Currency unit (e.g. `USD`)                                                                                         |
+| `costMetadata`  | Additional pricing context, including tier information, error details, and provider-reported cost source and scope |
 
 ## Correlation with traces
 

package/.docs/reference/server/routes.md

@@ -171,17 +171,31 @@ The route returns:
 
 ## Workflows
 
-| Method | Path                                      | Description                     |
-| ------ | ----------------------------------------- | ------------------------------- |
-| `GET`  | `/api/workflows`                          | List all workflows              |
-| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID              |
-| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run       |
-| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result |
-| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution       |
-| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow       |
-| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously           |
-| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
-| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
+| Method | Path                                      | Description                                           |
+| ------ | ----------------------------------------- | ----------------------------------------------------- |
+| `GET`  | `/api/workflows`                          | List all workflows                                    |
+| `GET`  | `/api/workflows/run-counts`               | Get per-workflow counts of running and suspended runs |
+| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID                                    |
+| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run                             |
+| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result                       |
+| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution                             |
+| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow                             |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously                                 |
+| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs                                    |
+| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                                      |
+
+### Run counts response
+
+The `/api/workflows/run-counts` endpoint returns counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs for every registered workflow. The record is keyed by the workflow's registry key from the Mastra config, and the server may cache the response for a few seconds:
+
+```typescript
+{
+  [workflowRegistryKey: string]: {
+    running: number;
+    suspended: number;
+  };
+}
+```
 
 ### Stored workflows
 

package/.docs/reference/storage/composite.md

@@ -251,6 +251,64 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
+## Closing connections
+
+`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({ id: 'composite', default: pgStore }),
+})
+
+process.on('SIGTERM', async () => {
+  // Releases the Postgres pool, so the process can exit
+  await mastra.shutdown()
+})
+```
+
+A store you construct only to supply a domain isn't reachable through the composite. Keep a reference to it and close it yourself:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ClickhouseStore } from '@mastra/clickhouse'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const clickhouseStore = new ClickhouseStore({
+  id: 'clickhouse-storage',
+  url: process.env.CLICKHOUSE_URL,
+  username: process.env.CLICKHOUSE_USERNAME,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: { observability: clickhouseStore.stores?.observability },
+  }),
+})
+
+process.on('SIGTERM', async () => {
+  await mastra.shutdown()
+  await clickhouseStore.close()
+})
+```
+
 ## Use cases
 
 ### Separate databases for different workloads

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -0,0 +1,117 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# createBedrockKBTool()
+
+The `createBedrockKBTool()` function creates a tool that retrieves relevant documents from an Amazon Bedrock Knowledge Base. It supports both managed search configuration and agentic retrieval (query decomposition and managed reranking) with automatic fallback to standard retrieval.
+
+## Usage example
+
+```typescript
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+  region: 'us-west-2',
+  numberOfResults: 5,
+  useAgenticRetrieval: true,
+})
+```
+
+### With an Agent
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+})
+
+const agent = new Agent({
+  name: 'KnowledgeAssistant',
+  instructions: 'Use the knowledge base tool to answer questions.',
+  model: myModel,
+  tools: { kb: kbTool },
+})
+```
+
+## Parameters
+
+**knowledgeBaseId** (`string`): The ID of the Amazon Bedrock Knowledge Base to query.
+
+**region** (`string`): AWS region where the Knowledge Base is deployed. Defaults to AWS\_REGION environment variable or us-east-1.
+
+**numberOfResults** (`number`): Maximum number of results to return. Defaults to 5.
+
+**useAgenticRetrieval** (`boolean`): Use AgenticRetrieveStream for complex queries with query decomposition and managed reranking. Falls back to standard Retrieve on failure. Defaults to true (disable with USE\_AGENTIC\_RETRIEVAL=false env var).
+
+**userId** (`string`): Default AWS user ID for document-level access control. A userId in the Mastra request context takes precedence.
+
+## Input Schema
+
+The tool accepts the following input when called by an agent:
+
+**queryText** (`string`): The search query to find relevant documents in the knowledge base.
+
+## Output Schema
+
+The tool returns an object with:
+
+**results** (`BedrockKBResult[]`): Array of retrieval results. Standard retrieval includes source and score when Bedrock provides them; agentic retrieval may omit those fields.
+
+### BedrockKBResult
+
+| Field      | Type                      | Description                                                                                                                           |
+| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
+| `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
+
+## Retrieval Modes
+
+### Agentic Retrieval (default)
+
+When `useAgenticRetrieval` is `true` (default), the tool uses `AgenticRetrieveStreamCommand` which:
+
+- Decomposes complex queries into sub-queries
+- Retrieves across multiple passes
+- Applies managed reranking for better results
+
+If agentic retrieval fails (e.g., older SDK, permissions), it automatically falls back to standard managed retrieval.
+
+### Standard Managed Retrieval
+
+When `useAgenticRetrieval` is `false`, the tool uses `RetrieveCommand` with `managedSearchConfiguration` for direct single-pass retrieval.
+
+## User-based access control
+
+Set `userId` in the Mastra request context to forward it as the Bedrock `userContext.userId`. This supports knowledge bases that enforce document-level access control. The request context value overrides the default `userId` configured on the tool.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const requestContext = new RequestContext()
+requestContext.set('userId', 'user-123')
+
+await agent.generate('Find my private documents', { requestContext })
+```
+
+## Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
+      "Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
+    }
+  ]
+}
+```
+
+## SDK Requirements
+
+- `@aws-sdk/client-bedrock-agent-runtime` >= 3.1000 (AgenticRetrieveStreamCommand requires \~3.1000+)

package/.docs/reference/voice/google.md

@@ -109,7 +109,17 @@ Converts speech to text using Google Cloud Speech-to-Text service. Supports both
 
 Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
 
+The v2 `recognize` call is IAM-authorized and does not accept API-key-only authentication. Configure service account credentials on the `listeningModel` (or set `GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` so the recognizer path can be resolved, even when `vertexAI` is not enabled.
+
 ```typescript
+import { GoogleVoice } from '@mastra/voice-google'
+
+// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
+// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
+const voice = new GoogleVoice({
+  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
+})
+
 const transcript = await voice.listen(iosSafariAacStream, {
   v2: true,
   config: {
@@ -118,6 +128,8 @@ const transcript = await voice.listen(iosSafariAacStream, {
 })
 ```
 
+> **Note:** `listen({ v2: true })` fails with `PERMISSION_DENIED` on `speech.recognizers.recognize` when only `GOOGLE_API_KEY` is set. An API-key request carries no OAuth identity, so granting `roles/speech.client` to a user account does not help — the role must be granted to the service account presented in the request. This applies regardless of the `vertexAI` setting; `speak()` and v1 `listen()` still work with an API key alone.
+
 **audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
 
 **options** (`GoogleListenOptionsV2`): v2 recognition options
@@ -162,7 +174,7 @@ The Google Voice provider supports two authentication methods:
 
 ### Standard Mode (API Key)
 
-Uses a Google Cloud API key for authentication. Suitable for development and basic use cases.
+Uses a Google Cloud API key for authentication. Covers `speak()` and v1 `listen()`. It does not cover `listen({ v2: true })`, which is IAM-authorized and requires service account credentials (see [v2](#v2)).
 
 ```typescript
 // Using environment variable (GOOGLE_API_KEY)
@@ -238,6 +250,8 @@ For Speech-to-Text:
 
 - `roles/speech.client` - Speech-to-Text Client
 
+Grant `roles/speech.client` to the service account whose credentials the request presents (via `keyFilename`, `credentials`, or `GOOGLE_APPLICATION_CREDENTIALS`). This role is required for `listen({ v2: true })` specifically, not only for Vertex AI mode. Granting it to a user account has no effect on API-key-only requests, which carry no identity to authorize.
+
 #### OAuth Scopes
 
 For synchronous Text-to-Speech synthesis:
@@ -269,6 +283,8 @@ For long-audio Text-to-Speech operations:
 
 6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
 
-7. Available voices can be filtered by language code using the `getSpeakers()` method.
+7. `listen({ v2: true })` requires service account credentials and `GOOGLE_CLOUD_PROJECT`; it fails with `PERMISSION_DENIED` when only `GOOGLE_API_KEY` is set. `speak()` and v1 `listen()` work with an API key alone.
+
+8. Available voices can be filtered by language code using the `getSpeakers()` method.
 
-8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.
+9. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.