@mastra/mcp-docs-server 1.2.0 → 1.2.1-alpha.0

package/.docs/models/providers.md

@@ -16,7 +16,10 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Alibaba (China)](https://mastra.ai/models/providers/alibaba-cn)
 - [Alibaba Coding Plan](https://mastra.ai/models/providers/alibaba-coding-plan)
 - [Alibaba Coding Plan (China)](https://mastra.ai/models/providers/alibaba-coding-plan-cn)
+- [Alibaba Token Plan](https://mastra.ai/models/providers/alibaba-token-plan)
+- [Alibaba Token Plan (China)](https://mastra.ai/models/providers/alibaba-token-plan-cn)
 - [Ambient](https://mastra.ai/models/providers/ambient)
+- [AnyAPI](https://mastra.ai/models/providers/anyapi)
 - [Atomic Chat](https://mastra.ai/models/providers/atomic-chat)
 - [Auriko](https://mastra.ai/models/providers/auriko)
 - [Bailing](https://mastra.ai/models/providers/bailing)
@@ -37,8 +40,8 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [DInference](https://mastra.ai/models/providers/dinference)
 - [evroc](https://mastra.ai/models/providers/evroc)
 - [FastRouter](https://mastra.ai/models/providers/fastrouter)
-- [Fireworks (Firepass)](https://mastra.ai/models/providers/firepass)
 - [Fireworks AI](https://mastra.ai/models/providers/fireworks-ai)
+- [FreeModel](https://mastra.ai/models/providers/freemodel)
 - [Friendli](https://mastra.ai/models/providers/friendli)
 - [FrogBot](https://mastra.ai/models/providers/frogbot)
 - [GitHub Models](https://mastra.ai/models/providers/github-models)
@@ -58,8 +61,9 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Lilac](https://mastra.ai/models/providers/lilac)
 - [Llama](https://mastra.ai/models/providers/llama)
 - [LLM Gateway](https://mastra.ai/models/providers/llmgateway)
+- [LLMTR](https://mastra.ai/models/providers/llmtr)
 - [LMStudio](https://mastra.ai/models/providers/lmstudio)
-- [LucidQuery AI](https://mastra.ai/models/providers/lucidquery)
+- [LucidQuery](https://mastra.ai/models/providers/lucidquery)
 - [Meganova](https://mastra.ai/models/providers/meganova)
 - [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax)
 - [MiniMax (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn)
@@ -74,6 +78,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
 - [NEAR AI Cloud](https://mastra.ai/models/providers/nearai)
 - [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
+- [Neon](https://mastra.ai/models/providers/neon)
 - [Neuralwatt](https://mastra.ai/models/providers/neuralwatt)
 - [Nova](https://mastra.ai/models/providers/nova)
 - [NovitaAI](https://mastra.ai/models/providers/novita-ai)
@@ -86,6 +91,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Perplexity](https://mastra.ai/models/providers/perplexity)
 - [Perplexity Agent](https://mastra.ai/models/providers/perplexity-agent)
 - [Poe](https://mastra.ai/models/providers/poe)
+- [Poolside](https://mastra.ai/models/providers/poolside)
 - [Privatemode AI](https://mastra.ai/models/providers/privatemode-ai)
 - [QiHang](https://mastra.ai/models/providers/qihang-ai)
 - [Qiniu](https://mastra.ai/models/providers/qiniu-ai)
@@ -96,15 +102,17 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Scaleway](https://mastra.ai/models/providers/scaleway)
 - [SiliconFlow](https://mastra.ai/models/providers/siliconflow)
 - [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)
+- [Snowflake Cortex](https://mastra.ai/models/providers/snowflake-cortex)
 - [STACKIT](https://mastra.ai/models/providers/stackit)
 - [StepFun](https://mastra.ai/models/providers/stepfun)
-- [StepFun](https://mastra.ai/models/providers/stepfun-ai)
+- [StepFun AI](https://mastra.ai/models/providers/stepfun-ai)
 - [submodel](https://mastra.ai/models/providers/submodel)
 - [Synthetic](https://mastra.ai/models/providers/synthetic)
 - [Tencent Coding Plan (China)](https://mastra.ai/models/providers/tencent-coding-plan)
 - [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)
 - [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)
 - [Together AI](https://mastra.ai/models/providers/togetherai)
+- [Umans AI](https://mastra.ai/models/providers/umans-ai)
 - [Umans AI Coding Plan](https://mastra.ai/models/providers/umans-ai-coding-plan)
 - [Upstage](https://mastra.ai/models/providers/upstage)
 - [Vivgrid](https://mastra.ai/models/providers/vivgrid)
@@ -118,6 +126,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Xpersona](https://mastra.ai/models/providers/xpersona)
 - [Z.AI](https://mastra.ai/models/providers/zai)
 - [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)
+- [Zeldoc](https://mastra.ai/models/providers/zeldoc)
 - [ZenMux](https://mastra.ai/models/providers/zenmux)
 - [Zhipu AI](https://mastra.ai/models/providers/zhipuai)
 - [Zhipu AI Coding Plan](https://mastra.ai/models/providers/zhipuai-coding-plan)

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

@@ -215,7 +215,7 @@ agent.sendMessage('Continue with the next step.', {
 })
 ```
 
-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.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the message: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the message is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the message and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored message. `accepted` resolves for routing — a generation error on a `wake` run surfaces through `output.consumeStream()` — and rejects only when the message could not be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 ### `queueMessage(message, options)`
 
@@ -228,7 +228,7 @@ agent.queueMessage('Also check whether the tests need updates.', {
 })
 ```
 
-`queueMessage()` accepts the same `message` and `options` shape as `sendMessage()` and returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`.
+`queueMessage()` accepts the same `message` and `options` shape as `sendMessage()` and returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`, with the same `accepted` semantics as `sendMessage()`.
 
 ### `sendSignal(signal, options)`
 
@@ -258,7 +258,20 @@ Sends a signal to an active run or memory thread.
 
 **options.ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is idle.
 
-Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `action` mirrors the winning `behavior` from `ifActive`/`ifIdle`. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored signal. `accepted` resolves for routing — a generation error on a `wake` run surfaces through `output.consumeStream()` — and rejects only when the signal could not be routed or started at all (e.g. a misconfigured agent). `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory. On the `wake` action, `output` is the agent stream for in-process consumption.
+
+In serverless handlers, await `accepted` and pass the `wake` output to your platform's `waitUntil` equivalent so the winning process can drain the stream after the HTTP response returns.
+
+```typescript
+const result = agent.sendSignal(signal, { resourceId, threadId })
+ctx.waitUntil(
+  result.accepted.then(async accepted => {
+    if (accepted.action === 'wake') {
+      await accepted.output.consumeStream()
+    }
+  }),
+)
+```
 
 ### `sendStateSignal(state, options)`
 
@@ -306,7 +319,7 @@ const result = await agent.sendStateSignal(
 
 **options** (`object`): Targeting and delivery behavior for the state signal. Accepts the same options as \`sendSignal()\`.
 
-Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` when Mastra accepts new state. Returns `{ accepted: true, skipped: true, reason: 'unchanged' }` when the same `cacheKey` and mode are already current for the state lane.
+Returns `{ accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` when Mastra accepts new state. Returns `{ skipped: true, reason: 'unchanged' }` when the same `cacheKey` and mode are already current for the state lane. `accepted` resolves at decision-time, once Mastra decides what to do with the signal: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run (including when this process loses a cross-process wake race), or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` is the authoritative id of the run that handled the signal and is present only on `wake` and `deliver`; for `persist`/`discard` use `result.signal.id` to correlate the stored signal. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 ### `sendNotificationSignal(notification, options)`
 
@@ -358,7 +371,7 @@ const result = await agent.sendNotificationSignal(
 
 **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when an immediate notification wakes an idle thread.
 
-Returns `{ accepted: true, record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void> }`. `record` is the stored inbox record. `decision` is the delivery-policy result. `signal` and `runId` are present when ingress emits a signal immediately, including the immediate summary emitted for active high-priority notifications. `persisted` is present when the emitted signal is persisted without waking an idle thread.
+Returns `{ record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void>, accepted?: Promise<SendAgentSignalAccepted> }`. `record` is the stored inbox record. `decision` is the delivery-policy result. `signal` and `runId` are present when ingress emits a signal immediately, including the immediate summary emitted for active high-priority notifications. `persisted` is present when the emitted signal is persisted without waking an idle thread. `accepted` is present when a signal is emitted and resolves at decision-time, once Mastra decides what to do with it: `{ action: 'wake', runId, output }` when this process runs the agent (it started or won the lease to start the run), `{ action: 'deliver', runId }` when the signal is forwarded onto an existing run, or `{ action: 'persist' }` / `{ action: 'discard' }` when nothing ran. `runId` on the accepted result is present only on `wake` and `deliver`. On the `wake` action, `output` is the agent stream for in-process consumption.
 
 Default delivery is priority-aware. `urgent` notifications deliver immediately. `high` notifications deliver immediately when the thread is idle; when the thread is active, Mastra emits a summary immediately and keeps `deliverAt` for later full delivery when the thread is idle. `medium` notifications deliver immediately when idle and batch into summaries when active. `low` notifications batch into summaries in both active and idle threads; idle low-priority summaries reach subscribers without waking the model loop. For the full flow, visit [Signals](https://mastra.ai/docs/agents/signals).
 

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

@@ -134,7 +134,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **modelUseCountProvider** (`ModelUseCountProvider`): Provides per-model use counts for sorting and display in \`listAvailableModels()\`.
 
-**modelUseCountTracker** (`ModelUseCountTracker`): Callback invoked when a model is selected via \`switchModel()\`. Use to track and persist model usage for ranking.
+**modelUseCountTracker** (`ModelUseCountTracker`): Callback invoked when a model is selected via \`session.model.switch()\`. Use to track and persist model usage for ranking.
 
 **customModelCatalogProvider** (`CustomModelCatalogProvider`): Catalog hook for additional models (e.g., user-defined custom providers). Returned entries are merged into \`listAvailableModels()\`.
 
@@ -234,45 +234,9 @@ const modes = harness.listModes()
 
 To read the active mode, use [`session.mode.get()`](https://mastra.ai/reference/harness/session); to resolve it to a full `HarnessMode`, use [`session.mode.resolve()`](https://mastra.ai/reference/harness/session).
 
-#### `switchMode({ modeId })`
-
-Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.
-
-```typescript
-await harness.switchMode({ modeId: 'build' })
-```
-
 ### Models
 
-To read the active model ID, use [`session.model.get()`](https://mastra.ai/reference/harness/session); to check whether a model is selected, use [`session.model.hasSelection()`](https://mastra.ai/reference/harness/session).
-
-#### `getModelName()`
-
-Return a short display name from the current model ID. For example, `"claude-sonnet-4"` from `"anthropic/claude-sonnet-4"`.
-
-```typescript
-const name = harness.getModelName()
-```
-
-#### `getFullModelId()`
-
-Return the complete model ID string.
-
-```typescript
-const fullId = harness.getFullModelId()
-```
-
-#### `switchModel({ modelId, scope?, modeId? })`
-
-Switch the active model. When `scope` is `'thread'`, the model ID is persisted to thread metadata so it's restored when switching back. Emits a `model_changed` event.
-
-```typescript
-// Set for current session only
-await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6' })
-
-// Persist to the current thread
-await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6', scope: 'thread' })
-```
+To read the active model ID, use [`session.model.get()`](https://mastra.ai/reference/harness/session); for a short display name, use [`session.model.displayName()`](https://mastra.ai/reference/harness/session); to check whether a model is selected, use [`session.model.hasSelection()`](https://mastra.ai/reference/harness/session).
 
 #### `getCurrentModelAuthStatus()`
 
@@ -469,33 +433,6 @@ harness.respondToToolSuspension({
 
 ### Permissions
 
-The harness owns the permission _policy_ — the rules that decide when a tool requires approval. Session-scoped _grants_ (which tools and categories are auto-approved for the current conversation) live on the session: see [`session.grantCategory()`](https://mastra.ai/reference/harness/session), [`session.grantTool()`](https://mastra.ai/reference/harness/session), and [`session.getGrants()`](https://mastra.ai/reference/harness/session).
-
-#### `setPermissionForCategory({ category, policy })`
-
-Set the permission policy for a tool category.
-
-```typescript
-harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })
-```
-
-#### `setPermissionForTool({ toolName, policy })`
-
-Set the permission policy for a specific tool. Per-tool policies take precedence over category policies.
-
-```typescript
-harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })
-```
-
-#### `getPermissionRules()`
-
-Return the current permission rules.
-
-```typescript
-const rules = harness.getPermissionRules()
-// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
-```
-
 #### `getToolCategory({ toolName })`
 
 Resolve a tool's category using the configured `toolCategoryResolver`.
@@ -575,78 +512,7 @@ if (record) {
 }
 ```
 
-#### `getObserverModelId()`
-
-Return the observer model ID from state or the default from `omConfig`.
-
-```typescript
-const modelId = harness.getObserverModelId()
-```
-
-#### `getReflectorModelId()`
-
-Return the reflector model ID from state or the default from `omConfig`.
-
-```typescript
-const modelId = harness.getReflectorModelId()
-```
-
-#### `switchObserverModel({ modelId })`
-
-Switch the observer model. Persists the setting to thread metadata and emits an `om_model_changed` event.
-
-```typescript
-await harness.switchObserverModel({ modelId: 'anthropic/claude-haiku-4-5' })
-```
-
-#### `switchReflectorModel({ modelId })`
-
-Switch the reflector model. Persists the setting to thread metadata and emits an `om_model_changed` event.
-
-```typescript
-await harness.switchReflectorModel({ modelId: 'anthropic/claude-haiku-4-5' })
-```
-
-#### `getObservationThreshold()`
-
-Return the observation threshold in tokens from state or the default from `omConfig`.
-
-```typescript
-const threshold = harness.getObservationThreshold()
-```
-
-#### `getReflectionThreshold()`
-
-Return the reflection threshold in tokens from state or the default from `omConfig`.
-
-```typescript
-const threshold = harness.getReflectionThreshold()
-```
-
-### Subagents
-
-#### `getSubagentModelId({ agentType? })`
-
-Retrieve the subagent model ID. Prioritizes per-type settings over the global setting.
-
-```typescript
-const modelId = harness.getSubagentModelId({ agentType: 'explore' })
-```
-
-#### `setSubagentModelId({ modelId, agentType? })`
-
-Set the subagent model ID. Pass an `agentType` to set a per-type override, or omit it to set the global default. Persists to thread settings and emits a `subagent_model_changed` event.
-
-```typescript
-// Set global subagent model
-await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })
-
-// Set per-type model
-await harness.setSubagentModelId({
-  modelId: 'anthropic/claude-haiku-4-5',
-  agentType: 'explore',
-})
-```
+The observer/reflector model selection and observation/reflection thresholds live on the Session under [`session.om`](https://mastra.ai/reference/harness/session), grouped by role. Read them with `session.om.observer.modelId()` / `session.om.reflector.modelId()` and `session.om.observer.threshold()` / `session.om.reflector.threshold()`, and change a role's model with `session.om.observer.switchModel()` / `session.om.reflector.switchModel()`.
 
 ### Forked subagents
 

package/.docs/reference/harness/session.md

@@ -221,7 +221,7 @@ await harness.session.thread.deleteSetting({ key: 'omThreshold' })
 
 ## Mode
 
-`session.mode` owns the active mode selection. Switching modes is performed on the [`Harness`](https://mastra.ai/reference/harness/harness-class) because it emits events and rebinds the stream.
+`session.mode` owns the active mode selection.
 
 ### `session.mode.get()`
 
@@ -239,9 +239,17 @@ Return the full `HarnessMode` object for the active mode, resolved against the h
 const mode = harness.session.mode.resolve()
 ```
 
+### `session.mode.switch({ modeId })`
+
+Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.
+
+```typescript
+await harness.session.mode.switch({ modeId: 'build' })
+```
+
 ## Model
 
-`session.model` owns the active model selection, including per-mode model memory. Switching models is performed on the [`Harness`](https://mastra.ai/reference/harness/harness-class).
+`session.model` owns the active model selection, including per-mode model memory.
 
 ### `session.model.get()`
 
@@ -251,6 +259,14 @@ Return the active model ID.
 const modelId = harness.session.model.get()
 ```
 
+### `session.model.displayName()`
+
+Return a short display name for the active model: the last segment of the model ID (for example, `claude-sonnet-4` from `anthropic/claude-sonnet-4`). Returns `'unknown'` when no model is selected.
+
+```typescript
+const name = harness.session.model.displayName()
+```
+
 ### `session.model.hasSelection()`
 
 Check whether a model is currently selected.
@@ -261,6 +277,116 @@ if (harness.session.model.hasSelection()) {
 }
 ```
 
+### `session.model.switch({ modelId, scope?, modeId? })`
+
+Switch the active model. When `scope` is `'thread'` (the default), the model ID is persisted as the per-mode model so it's restored when switching back. Reports the selection to the harness's `modelUseCountTracker` and emits a `model_changed` event.
+
+```typescript
+// Set for the current session only
+await harness.session.model.switch({
+  modelId: 'anthropic/claude-sonnet-4-6',
+  scope: 'global',
+})
+
+// Persist to the current thread (default)
+await harness.session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })
+```
+
+## Observational Memory
+
+The observational-memory model selection, grouped by role under `session.om.observer` and `session.om.reflector`. Both roles expose the same methods. Reads return the value from session state when set, falling back to the harness's `omConfig` defaults.
+
+### `session.om.observer.modelId()` / `session.om.reflector.modelId()`
+
+Return the role's model ID, or `undefined` when neither session state nor `omConfig` provides one.
+
+```typescript
+const observer = harness.session.om.observer.modelId()
+const reflector = harness.session.om.reflector.modelId()
+```
+
+### `session.om.observer.threshold()` / `session.om.reflector.threshold()`
+
+Return the role's threshold in tokens (observation threshold for the observer, reflection threshold for the reflector), or `undefined` when unset.
+
+```typescript
+const observationThreshold = harness.session.om.observer.threshold()
+const reflectionThreshold = harness.session.om.reflector.threshold()
+```
+
+### `session.om.observer.switchModel({ modelId })` / `session.om.reflector.switchModel({ modelId })`
+
+Switch the role's model. Persists the setting to thread metadata and emits an `om_model_changed` event.
+
+```typescript
+await harness.session.om.observer.switchModel({ modelId: 'anthropic/claude-haiku-4-5' })
+await harness.session.om.reflector.switchModel({ modelId: 'anthropic/claude-haiku-4-5' })
+```
+
+### `session.om.observer.resolvedModel()` / `session.om.reflector.resolvedModel()`
+
+Resolve the role's model ID to a model instance via the harness's `resolveModel`, or `undefined` when no model ID is set or no resolver is configured.
+
+```typescript
+const observerModel = harness.session.om.observer.resolvedModel()
+```
+
+## Permissions
+
+`session.permissions` owns the persisted tool-approval _policy_ — the per-category and per-tool rules consulted during approval resolution. These are distinct from the in-memory session _grants_ documented under [Methods → Permissions](#permissions); grants reset each session, whereas these rules are persisted in session state.
+
+### `session.permissions.getRules()`
+
+Return the current permission rules, or empty rules (`{ categories: {}, tools: {} }`) when none are set.
+
+```typescript
+const rules = harness.session.permissions.getRules()
+// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
+```
+
+### `session.permissions.setForCategory({ category, policy })`
+
+Set the approval policy (`'allow' | 'ask' | 'deny'`) for a tool category. Resolves once the change is persisted to session state.
+
+```typescript
+await harness.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
+```
+
+### `session.permissions.setForTool({ toolName, policy })`
+
+Set the approval policy for a specific tool. Per-tool policies take precedence over category policies. Resolves once persisted.
+
+```typescript
+await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+```
+
+## Subagents
+
+`session.subagents` owns subagent configuration. It currently exposes the subagent model selection under `session.subagents.model`.
+
+### `session.subagents.model.get({ agentType? })`
+
+Return the subagent model ID, preferring the per-`agentType` value when one is given, then the global subagent model, or `null` when neither is set.
+
+```typescript
+const modelId = harness.session.subagents.model.get({ agentType: 'explore' })
+```
+
+### `session.subagents.model.set({ modelId, agentType? })`
+
+Set the subagent model ID. Pass an `agentType` to set a per-type override, or omit it to set the global default. Persists to thread settings and emits a `subagent_model_changed` event.
+
+```typescript
+// Set the global subagent model
+await harness.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
+
+// Set a per-type override
+await harness.session.subagents.model.set({
+  modelId: 'anthropic/claude-haiku-4-5',
+  agentType: 'explore',
+})
+```
+
 ## Run
 
 `session.run` owns run and trace identity plus abort state for the in-flight run.

package/.docs/reference/index.md

@@ -335,6 +335,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.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)
+- [ArchilFilesystem](https://mastra.ai/reference/workspace/archil-filesystem)
 - [AzureBlobFilesystem](https://mastra.ai/reference/workspace/azure-blob-filesystem)
 - [BlaxelSandbox](https://mastra.ai/reference/workspace/blaxel-sandbox)
 - [DaytonaSandbox](https://mastra.ai/reference/workspace/daytona-sandbox)

package/.docs/reference/tools/mcp-client.md

@@ -167,6 +167,17 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 new Agent({ id: 'agent', tools: await mcp.listTools() })
 ```
 
+### `listToolsWithErrors()`
+
+Retrieves all tools from all configured servers, with tool names namespaced by their server name. Also returns per-server errors for servers that failed to connect or list tools.
+
+```typescript
+const { tools, errors } = await mcp.listToolsWithErrors()
+
+new Agent({ id: 'agent', tools })
+console.log(errors)
+```
+
 ### `listToolsets()`
 
 Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed dynamically into the generate or stream method.

package/.docs/reference/voice/google-gemini-live.md

@@ -146,6 +146,28 @@ Converts text to speech and sends it to the model. Can accept either a string or
 
 Returns: `Promise<void>` (responses are emitted via `speaker` and `writing` events)
 
+### `sendContext()`
+
+Sends conversation history into the live session without triggering a model response. Use this to seed prior turns (e.g. from Mastra Memory) on a cold connect so the model has context before the user speaks.
+
+```typescript
+await voice.sendContext([
+  { role: 'user', content: 'What is the weather?' },
+  { role: 'assistant', content: 'It is 72°F in San Francisco.' },
+])
+
+// Model stays silent until the user actually speaks.
+await voice.send(micStream)
+```
+
+**turns** (`IncrementalTurn[]`): Prior conversation turns to seed into the session. Each turn has a \`role\` ("user" or "assistant") and \`content\` string. Both roles are supported on newer models (e.g. \`gemini-2.5-flash-native-audio-preview-12-2025\`). Some older models only accept user-role turns.
+
+**options** (`object`): Optional configuration.
+
+**options.turnComplete** (`boolean`): Whether to mark the turn as complete and trigger a model response.
+
+Returns: `Promise<void>`
+
 ### `listen()`
 
 Processes audio input for speech recognition. Takes a readable stream of audio data and returns the transcribed text.