@mastra/mcp-docs-server 1.1.42-alpha.6 → 1.1.42-alpha.8

package/.docs/docs/agents/signals.md

@@ -233,9 +233,24 @@ Existing stored signal rows and older clients continue to load through the compa
 
 > **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
+## Approve tool calls
+
+When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The call returns a JSON acknowledgement. The resumed chunks arrive through the existing thread subscription.
+
+```typescript
+await agent.sendToolApproval({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+  toolCallId: 'tool-call_456',
+  approved: true,
+})
+```
+
+Pass `approved: false` to decline the same pending tool call. Use the older `approveToolCall()` and `declineToolCall()` methods only when you are rendering the separate continuation stream directly.
+
 ## Use HTTP routes
 
-If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
+If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. For subscription-native tool approval, use `POST /api/agents/:agentId/send-tool-approval`. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
 
 ## Use the client SDK
 
@@ -294,4 +309,5 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
-- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/editor/overview.md

@@ -66,6 +66,41 @@ Once registered, you can manage agents through [Studio](https://mastra.ai/docs/s
 
 > **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
+## Code and database sources
+
+The editor stores agent overrides in one of two sources, set with the `source` option on `MastraEditor`:
+
+| Source         | Where overrides live                                      | Studio actions                                           |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------- |
+| `db` (default) | The configured storage backend.                           | Save and publish drafts.                                 |
+| `code`         | Per-agent JSON files on disk, tracked in your repository. | Download the override file or save it to the filesystem. |
+
+The default `db` source is best when non-developers iterate through Studio and you want versioning, drafts, and runtime version targeting. The `code` source is best when overrides should live in your repository alongside the rest of your code, reviewed through pull requests and deployed with your application.
+
+To use the code source, set `source: 'code'`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: {
+    /* your existing agents */
+  },
+  editor: new MastraEditor({
+    source: 'code',
+  }),
+})
+```
+
+When `source` is `'code'`, the editor writes each override to a deterministic JSON file under `./mastra/editor/agents/<agentId>.json`. Set `codePath` to change the directory. Because the files are deterministic, every save produces a clean diff you can commit and review.
+
+### Versioning with the code source
+
+The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file appears as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
+
+This means versions and rollbacks are managed through Git rather than through draft and publish actions.
+
 ## Studio
 
 Go to the **Agents** tab in Studio and select an agent to edit. Select the **Editor** tab. You'll be taken to the editor interface, where you can modify the agent's instructions, tools, and variables.
@@ -114,15 +149,16 @@ The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and
 
 The same operations are available over HTTP through the Mastra server. Use these when you want to manage stored agents from a separate service or from a non-TypeScript client:
 
-| Method   | Path                            | Description               |
-| -------- | ------------------------------- | ------------------------- |
-| `GET`    | `/stored/agents`                | List all stored agents.   |
-| `POST`   | `/stored/agents`                | Create a stored agent.    |
-| `GET`    | `/stored/agents/:storedAgentId` | Get a stored agent by ID. |
-| `PATCH`  | `/stored/agents/:storedAgentId` | Update a stored agent.    |
-| `DELETE` | `/stored/agents/:storedAgentId` | Delete a stored agent.    |
+| Method   | Path                                   | Description                                                      |
+| -------- | -------------------------------------- | ---------------------------------------------------------------- |
+| `GET`    | `/stored/agents`                       | List all stored agents.                                          |
+| `POST`   | `/stored/agents`                       | Create a stored agent.                                           |
+| `GET`    | `/stored/agents/:storedAgentId`        | Get a stored agent by ID.                                        |
+| `PATCH`  | `/stored/agents/:storedAgentId`        | Update a stored agent.                                           |
+| `DELETE` | `/stored/agents/:storedAgentId`        | Delete a stored agent.                                           |
+| `POST`   | `/stored/agents/:storedAgentId/export` | Export a stored agent's override as a deterministic JSON config. |
 
-The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, and `client.getStoredAgent()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
+The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
 
 ### Automated experimentation
 
@@ -149,6 +185,32 @@ When you edit a code-defined agent through the editor, only specific fields can
 
 Fields like the agent's `id`, `name`, and `model` come from your code and can't be changed through the editor for code-defined agents. The variables are also read-only.
 
+### Controlling what is editable
+
+Use the `editor` field on a code-defined agent to control which fields the editor can override. This lets you keep some fields code-owned while allowing edits to others:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5.4',
+  editor: { instructions: true, tools: { description: true } },
+})
+```
+
+The `editor` field accepts these shapes:
+
+| Value                              | Result                                                     |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Omitted                            | Instructions and tools are editable.                       |
+| `false`                            | Nothing is editable. The agent is locked.                  |
+| `{ instructions: true }`           | Instructions are editable.                                 |
+| `{ tools: true }`                  | Tool membership and descriptions are editable.             |
+| `{ tools: { description: true } }` | Only tool descriptions are editable. Membership is locked. |
+
+When a field is owned by code, Studio shows it as read-only and the server strips it from saved overrides, so the stored config only contains the fields you allow. See the [`editor` overrides reference](https://mastra.ai/reference/agents/agent) for the full type.
+
 ## Versioning
 
 Every time you save changes to an agent or prompt block, a new version snapshot is created. Versions give you a full history of your agent's configuration. You can roll back to any previous state, compare what changed between two snapshots, and target specific versions per request for A/B testing or gradual rollouts.

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

@@ -258,6 +258,16 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **requestContextSchema** (`StandardJSONSchemaV1`): Standard JSON Schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
 
+**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Controls which fields the editor can override for this code-defined agent. Omit to allow editing instructions and tools. See Editor overrides below.
+
+## Editor overrides
+
+When you register the [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor), the `editor` field controls which parts of a code-defined agent can be changed through the editor. Fields owned by code are read-only in Studio and are stripped from saved overrides.
+
+**editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Omit to allow editing instructions and tools. Set to \`false\` to lock the agent. Set \`instructions: true\` to allow instruction edits. Set \`tools: true\` to allow tool membership and description edits, or \`tools: { description: true }\` to allow only description edits.
+
+The agent's `id`, `name`, and `model` always come from code and can't be overridden through the editor. See the [Editor overview](https://mastra.ai/docs/editor/overview) for usage.
+
 ## Returns
 
 **agent** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.

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

@@ -326,7 +326,7 @@ response.processDataStream({
 
 ### `approveToolCall()`
 
-Approve a pending tool call that requires human confirmation:
+Approve a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the approval response.
 
 ```typescript
 const response = await agent.approveToolCall({
@@ -341,9 +341,26 @@ response.processDataStream({
 })
 ```
 
+### `sendToolApproval()`
+
+Approve or decline a pending tool call for a subscribed thread. Use this with `subscribeToThread()` when the resumed chunks should arrive through the existing thread subscription instead of a separate continuation stream.
+
+```typescript
+const result = await agent.sendToolApproval({
+  resourceId: 'user-123',
+  threadId: 'thread-456',
+  toolCallId: 'tool-call-456',
+  approved: true,
+})
+
+console.log(result.accepted)
+```
+
+Returns `{ accepted: true, runId: string, toolCallId?: string }`.
+
 ### `declineToolCall()`
 
-Decline a pending tool call that requires human confirmation:
+Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response.
 
 ```typescript
 const response = await agent.declineToolCall({

package/.docs/reference/editor/mastra-editor.md

@@ -43,6 +43,10 @@ export const mastra = new Mastra({
 
 **builder** (`AgentBuilderOptions`): Agent Builder configuration. See the AgentBuilderOptions reference. Omit or set \`enabled: false\` to disable the Builder.
 
+**source** (`'code' | 'db'`): Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See the Editor overview for the difference. (Default: `'db'`)
+
+**codePath** (`string`): Directory used by the 'code' source for per-agent JSON files. Ignored when source is not 'code'. (Default: `'./mastra/editor/'`)
+
 ### Provider interfaces
 
 Each provider field above takes a record keyed by provider id. See the per-provider reference pages for the implementation shape:
@@ -209,4 +213,16 @@ Returns all registered sandbox providers.
 
 #### `getBlobStoreProviders()`
 
-Returns all registered blob store providers.
+Returns all registered blob store providers.
+
+### Source
+
+#### `getSource()`
+
+Returns the configured source (`'code'` or `'db'`), or `undefined` when the editor was constructed without an explicit `source`.
+
+```typescript
+const source = mastra.getEditor()?.getSource()
+```
+
+Returns: `'code' | 'db' | undefined`

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

@@ -4,19 +4,20 @@ Server adapters register these routes when you call `server.init()`. All routes
 
 ## Agents
 
-| Method | Path                                         | Description                                           |
-| ------ | -------------------------------------------- | ----------------------------------------------------- |
-| `GET`  | `/api/agents`                                | List all agents                                       |
-| `GET`  | `/api/agents/:agentId`                       | Get agent by ID (supports version query params)       |
-| `POST` | `/api/agents/:agentId/generate`              | Generate agent response                               |
-| `POST` | `/api/agents/:agentId/stream`                | Stream agent response                                 |
-| `POST` | `/api/agents/:agentId/send-message`          | Send a user message to an active or idle thread       |
-| `POST` | `/api/agents/:agentId/queue-message`         | Queue a user message for the next thread turn         |
-| `POST` | `/api/agents/:agentId/signals`               | Send a lower-level signal to an active or idle thread |
-| `POST` | `/api/agents/:agentId/subscribe-thread`      | Subscribe to a thread stream                          |
-| `POST` | `/api/agents/:agentId/resume-stream`         | Resume a suspended agent stream with custom data      |
-| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools                                      |
-| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool                                    |
+| Method | Path                                         | Description                                                             |
+| ------ | -------------------------------------------- | ----------------------------------------------------------------------- |
+| `GET`  | `/api/agents`                                | List all agents                                                         |
+| `GET`  | `/api/agents/:agentId`                       | Get agent by ID (supports version query params)                         |
+| `POST` | `/api/agents/:agentId/generate`              | Generate agent response                                                 |
+| `POST` | `/api/agents/:agentId/stream`                | Stream agent response                                                   |
+| `POST` | `/api/agents/:agentId/send-message`          | Send a user message to an active or idle thread                         |
+| `POST` | `/api/agents/:agentId/queue-message`         | Queue a user message for the next thread turn                           |
+| `POST` | `/api/agents/:agentId/signals`               | Send a lower-level signal to an active or idle thread                   |
+| `POST` | `/api/agents/:agentId/threads/subscribe`     | Subscribe to a thread stream                                            |
+| `POST` | `/api/agents/:agentId/send-tool-approval`    | Approve or decline a tool call and resume through a thread subscription |
+| `POST` | `/api/agents/:agentId/resume-stream`         | Resume a suspended agent stream with custom data                        |
+| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools                                                        |
+| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool                                                      |
 
 ### Get agent query parameters
 
@@ -140,6 +141,32 @@ Both routes return:
 }
 ```
 
+### Subscription tool approval routes
+
+Use `POST /api/agents/:agentId/send-tool-approval` when the client already has an active thread subscription. The route resumes the run and returns a JSON acknowledgement. Resumed stream chunks are delivered through `POST /api/agents/:agentId/threads/subscribe`.
+
+The route accepts this request body:
+
+```typescript
+{
+  resourceId: string;
+  threadId: string;
+  toolCallId: string;
+  approved: boolean;
+  requestContext?: Record<string, unknown>;
+}
+```
+
+The route returns:
+
+```typescript
+{
+  accepted: true;
+  runId: string;
+  toolCallId?: string;
+}
+```
+
 ## Workflows
 
 | Method | Path                                      | Description                     |

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

@@ -242,7 +242,9 @@ The GeminiLiveVoice class emits the following events:
 
 **speaking** (`event`): Emitted with audio metadata. Callback receives { audioData?: Int16Array, sampleRate?: number }.
 
-**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }.
+**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }. On native-audio models the assistant transcript is driven by the server's \`output\_audio\_transcription\` channel rather than \`modelTurn.parts.text\`.
+
+**thinking** (`event`): Emitted on native-audio models with the model's chain-of-thought / reasoning text from \`modelTurn.parts.text\`. Callback receives { text: string }. Does not fire on non-native-audio models, where \`modelTurn.parts.text\` is the spoken response and is emitted as \`writing\` instead.
 
 **session** (`event`): Emitted on session state changes. Callback receives { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object }.
 
@@ -254,7 +256,18 @@ The GeminiLiveVoice class emits the following events:
 
 **error** (`event`): Emitted when an error occurs. Callback receives { message: string, code?: string, details?: unknown }.
 
-**interrupt** (`event`): Interrupt events. Callback receives { type: 'user' | 'model', timestamp: number }.
+**interrupt** (`event`): Emitted on barge-in when the user starts speaking over an in-flight model response. The server cancels any further audio for the current turn. Callback receives { type: 'user', timestamp: number }.
+
+## Native-audio behavior
+
+Native-audio Gemini Live models — any model whose ID contains `native-audio`, such as `gemini-2.5-flash-native-audio-preview-12-2025` — split text output across two channels:
+
+- The model's spoken reply is delivered as audio plus an `output_audio_transcription` transcript and surfaced as `writing` with `role: 'assistant'`.
+- The model's internal reasoning is delivered as `modelTurn.parts.text` and surfaced as `thinking`.
+
+On non-native-audio models there is no `output_audio_transcription` channel, so `modelTurn.parts.text` is the spoken response itself and is emitted as `writing`; the `thinking` event does not fire.
+
+Input transcription, output transcription, and barge-in detection (`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`) are enabled automatically in the setup payload — no extra configuration is required.
 
 ## Available models
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.42-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [[`19a8658`](https://github.com/mastra-ai/mastra/commit/19a86589c788ef48bb6c1b0612cc82a201857379), [`a659a77`](https://github.com/mastra-ai/mastra/commit/a659a779bdebe3a52a518c56d2260592d0240fe0), [`3332be9`](https://github.com/mastra-ai/mastra/commit/3332be9701ecd77aba840959d9a1d1ce7aef02d3)]:
+  - @mastra/core@1.38.0-alpha.6
+
+## 1.1.42-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`a18775a`](https://github.com/mastra-ai/mastra/commit/a18775a693172546ee2378d39b67d4e32895b251), [`1baf2d1`](https://github.com/mastra-ai/mastra/commit/1baf2d152c6881338ff8f114633d5316fe13dd15)]:
+  - @mastra/core@1.38.0-alpha.5
+
 ## 1.1.42-alpha.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.42-alpha.6",
+  "version": "1.1.42-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.38.0-alpha.4",
-    "@mastra/mcp": "^1.9.0-alpha.0"
+    "@mastra/mcp": "^1.9.0-alpha.0",
+    "@mastra/core": "1.38.0-alpha.6"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -47,7 +47,7 @@
     "vitest": "4.1.5",
     "@internal/lint": "0.0.99",
     "@internal/types-builder": "0.0.74",
-    "@mastra/core": "1.38.0-alpha.4"
+    "@mastra/core": "1.38.0-alpha.6"
   },
   "homepage": "https://mastra.ai",
   "repository": {