@mastra/mcp-docs-server 1.2.26-alpha.1 → 1.2.26-alpha.7

package/.docs/docs/agents/overview.md

@@ -76,7 +76,7 @@ Short list of known model IDs are:
 
 Go to <https://mastra.ai/models> for a full list of supported models.
 
-Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
+Add a tool to an agent by importing the tool and passing it to the agent constructor as a tools object.
 
 Example:
 

package/.docs/docs/agents/processors.md

@@ -976,6 +976,27 @@ export class ContextLengthHandler implements Processor {
 
 Mastra includes a built-in [`PrefillErrorHandler`](https://mastra.ai/reference/processors/prefill-error-handler) that automatically handles the Anthropic "assistant message prefill" error. This processor is auto-injected and requires no configuration.
 
+## Receive background work notifications
+
+Use `createBackgroundWorkSignalProcessor()` to retain the active caller's signal capability for eligible background tool calls:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBackgroundWorkSignalProcessor } from '@mastra/core/processors'
+
+const agent = new Agent({
+  id: 'background-agent',
+  name: 'Background agent',
+  instructions: 'Complete tasks using the available tools.',
+  model: 'openai/gpt-5.6-sol',
+  inputProcessors: [createBackgroundWorkSignalProcessor()],
+})
+```
+
+Mastra's background runtime remains responsible for execution, persistence, retries, result reconciliation, and continuation. The processor only retains caller-scoped notification access. When background work starts, it emits `work-deferred` or `work-awaited` with `status: 'running'`. After the authoritative tool result is reconciled, it emits `work-completed` or `work-failed`.
+
+Notifications are process-local and best-effort. If the originating run has already ended or the signal can't be delivered (for example, because the task resumed on another process), Mastra preserves the authoritative result without recreating the run or retrying the notification. Foreground calls never emit background work notifications because there is no detached work to report.
+
 ## Related documentation
 
 - [Agent lifecycle](https://mastra.ai/docs/guides/agent-lifecycle): Full-run ordering and `RequestContext` visibility

package/.docs/docs/deployment/mastra-server.md

@@ -143,9 +143,15 @@ To add your own endpoints, see [Custom API Routes](https://mastra.ai/docs/server
 
 ## Graceful shutdown and rolling deploys
 
-By default, the generated server handles `SIGINT` and `SIGTERM`. It stops accepting connections, waits up to [`server.drainTimeout`](https://mastra.ai/reference/configuration) for active requests and streams, then runs `mastra.shutdown()`. The drain timeout defaults to 5 seconds. A second signal terminates the process immediately. See [`server.handleShutdownSignals`](https://mastra.ai/reference/configuration) if you need to manage signals yourself.
+By default, the generated server handles `SIGINT` and `SIGTERM`. It stops accepting connections, waits up to [`server.drainTimeout`](https://mastra.ai/reference/configuration) for active requests and streams, then runs `mastra.shutdown()`. Shutdown gives in-flight workflow runs (including durable agent runs) the same drain window to finish before workers and pub/sub subscriptions are torn down. The drain timeout defaults to 5 seconds. A second signal terminates the process immediately. See [`server.handleShutdownSignals`](https://mastra.ai/reference/configuration) if you need to manage signals yourself.
 
-Increase `drainTimeout` when your hosting platform's termination grace period can accommodate longer turns. Keep enough time after the drain for shutdown cleanup.
+Increase `drainTimeout` when your hosting platform's termination grace period can accommodate longer turns. The HTTP drain and the workflow drain run one after the other, so keep enough time for both plus shutdown cleanup.
+
+If you call `mastra.shutdown()` yourself, pass `drainTimeout` to control how long it waits for in-flight workflow runs:
+
+```typescript
+await mastra.shutdown({ drainTimeout: 30_000 })
+```
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'

package/.docs/docs/evals/datasets.md

@@ -142,7 +142,11 @@ Deleting an item hides it from the current dataset version but retains its conte
 await dataset.purgeItem({ itemId: 'item-abc-123' })
 ```
 
-Purging replaces content in every historical row and deletion tombstone present during the operation with redacted values, and scrubs linked experiment-result payloads, tags, and comments. Later experiment-result submissions for the item are also stored with redacted content, and later `updateItem()` calls reject with `DATASET_ITEM_PURGED`. Don't run purge concurrently with dataset item updates or deletions because a write that started before purge can commit a stale revision afterward. Purging keeps version, identity, experiment counters, and review status so pinned dataset versions and experiment records remain structurally consistent. It doesn't create a dataset version and can't be undone. Avoid storing sensitive data in `externalId`, which remains unchanged as the item's identity key.
+Purging replaces content in every historical row and deletion tombstone with redacted values, and scrubs linked experiment-result payloads, tags, and comments. Later experiment-result submissions for the item are also stored with redacted content.
+
+Purge serializes or conflicts with concurrent dataset item writers without guaranteeing which operation completes first. If a mutating `updateItem()` call loses the race, it re-reads the purge marker and rejects with `DATASET_ITEM_PURGED`. `deleteItem()` remains idempotent, and any deletion tombstone created during the race stays redacted.
+
+Normal item mutations use Slowly Changing Dimension Type 2 (SCD-2) versioning. Permanent purge intentionally overrides historical immutability for erasure while preserving item identity and the dataset version timeline. It doesn't create a dataset version and can't be undone. Experiment counters and review status are also preserved. Avoid storing sensitive data in `externalId`, which remains unchanged as the item's identity key.
 
 MongoDB storage requires a replica set or sharded deployment with transaction support for this operation. Purging fails before changing data when MongoDB transactions aren't available.
 

package/.docs/docs/guides/context-engineering.md

@@ -178,7 +178,7 @@ await assistant.generate('Help me plan the next project milestone.', {
 
 The example assumes storage is configured on the registered Mastra instance or directly on `Memory`. `lastMessages` controls how many recent messages Mastra loads from the thread. The default is 10.
 
-Message history works well for shorter conversations where recent turns contain the context the agent needs. For long-running conversations, Mastra recommends [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps recent conversation available and turns older history into a dense observation log.
+Message history works well for shorter conversations where recent turns contain the context the agent needs. Because the `lastMessages` window slides forward on every request, each turn past the limit removes the oldest message from the start of the prompt and invalidates the provider prompt cache. For long-running conversations, Mastra recommends [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps recent conversation available and turns older history into a dense observation log while keeping the prompt prefix stable for caching.
 
 ## Observational Memory
 

package/.docs/docs/harness/background-tasks.md

@@ -44,16 +44,16 @@ The full set of options is listed in the [backgroundTasks configuration referenc
 
 ## Run a tool in the background
 
-Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. Tools opt in at one of two layers:
+Enabling the manager doesn't run anything in the background by itself. Tools become eligible at one of two layers:
 
 1. **Tool-level config**: the tool itself declares it as background-eligible.
 2. **Agent-level config**: the agent declares which of its tools are background-eligible.
 
-Once a tool has opted in, the LLM can optionally include a `_background` field in the tool arguments to override the resolved config for a specific call (timeout, retries, or to flip the call back to foreground).
+Eligible tools default to `deferred` execution. Set `defaultDisposition: 'foreground'` at either layer when eligibility should only give the LLM the option to run a call in the background. The LLM can include a `_background` field in the tool arguments to select `foreground`, `deferred`, or `awaited` execution for a specific call and override its timeout or retries.
 
 ### Tool-level
 
-Set `background.enabled: true` on the tool definition. Tools opted in at this layer run in the background whenever called by an agent that has the manager enabled.
+Set `background.enabled: true` on the tool definition. Tools opted in at this layer are eligible for background execution when called by an agent that has the manager enabled. Their configured default disposition determines whether each call runs inline or in the background unless the call includes a `_background` override.
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -65,6 +65,7 @@ export const researchTool = createTool({
   inputSchema: z.object({ topic: z.string() }),
   background: {
     enabled: true,
+    defaultDisposition: 'deferred',
     timeoutMs: 600_000,
     maxRetries: 1,
   },
@@ -104,20 +105,23 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 ```json
 {
   "topic": "solana",
-  "_background": { "enabled": true, "timeoutMs": 900_000 }
+  "_background": { "disposition": "awaited", "timeoutMs": 900000 }
 }
 ```
 
-The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer, it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+The available dispositions are:
 
-### Resolution order
+- `foreground`: Run the tool synchronously without background-work lifecycle signals.
+- `deferred`: Dispatch the tool and let the agent continue. The task remains attached to the run, and streams using `untilIdle` wait for it to reconcile.
+- `awaited`: Dispatch the tool through the background task manager, but hold the current branch until its authoritative result has been reconciled.
+
+For compatibility, `_background.enabled: true` selects `deferred`, and `_background.enabled: false` selects `foreground`. An explicit `disposition` takes precedence over `enabled`.
 
-When a tool call is dispatched, the resolved background config is computed in this priority order:
+The `_background` override only _modifies_ tools the developer has already opted in at the tool or agent layer. If a tool hasn't been opted in, a model-selected background disposition is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
 
-1. Agent-level `backgroundTasks.tools` entry for the tool.
-2. Tool-level `background` config.
-3. LLM `_background.enabled` override (only used to enable background dispatch when the tool was opted in at one of the layers above).
-4. Manager defaults (`defaultTimeoutMs`, `defaultRetries`).
+### Resolution order
+
+When a tool call is dispatched, agent-level and tool-level settings determine eligibility and fallback values. For an eligible tool, the LLM `_background` fields override the corresponding values for that call. Manager defaults fill timeout and retry values that remain unset. An `_background` field can't enable a tool that's not eligible.
 
 If the agent has `backgroundTasks.disabled: true`, every tool call runs synchronously regardless of the layers above.
 
@@ -204,7 +208,7 @@ const stream = await supervisor.stream('Research AI in education and write an ar
 
 ### Inheriting from the subagent
 
-If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but has background-eligible tools of its own (either via tool-level `background.enabled: true` or its own `backgroundTasks.tools` entry) the framework still dispatches the entire subagent invocation as a background task. The supervisor inherits the subagent's intent: the subagent itself becomes the background task, and its inner tools run in the foreground inside the subagent's loop.
+If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but has background-eligible tools of its own (either via tool-level `background.enabled: true` or its own `backgroundTasks.tools` entry) the framework still dispatches the entire subagent invocation as a background task. The supervisor inherits the subagent's intent: the subagent itself becomes the background task, and it can dispatch its eligible ordinary tools in the background inside its loop. Further delegated-agent calls run in the foreground.
 
 The background config used for the inherited dispatch (for example `waitTimeoutMs`) is derived from the subagent's own `backgroundTasks` config.
 
@@ -223,9 +227,11 @@ const researchAgent = new Agent({
 })
 ```
 
-When this `researchAgent` is delegated to from a supervisor that has no backgroundTask configuration for the `researchAgent`, the supervisor still dispatches the whole `researchAgent` invocation as a background task, and `deepResearchTool` runs in the foreground inside that invocation, instead of dispatching its own nested background task.
+When this `researchAgent` is delegated to from a supervisor that has no background task configuration for the `researchAgent`, the supervisor still dispatches the whole `researchAgent` invocation as a background task.
+
+Mastra supports one nested background-tool level inside a delegated run: a root agent can delegate to a subagent, and that subagent can dispatch an eligible ordinary tool in the background. A second delegated-agent edge runs in the foreground and doesn't receive nested background guidance. This limit is execution-scoped and doesn't mutate the shared subagent configuration.
 
-Use this pattern when you want a subagent to behave consistently in the background regardless of which supervisor invokes it. Use the supervisor-side opt-in (above) when you want to tune background behavior centrally per supervisor.
+Which layer to use depends on where consistency matters: subagent-level configuration travels with the agent, so its background behavior stays the same under every supervisor, whereas the supervisor-side opt-in above centralizes that tuning in one place. This boundary stops at a single nested delegation level and has no workflow integration.
 
 ## Suspending and resuming
 
@@ -315,23 +321,23 @@ export const mastra = new Mastra({
 Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
 
 ```typescript
-const bgManager = mastra.backgroundTaskManager
-if (!bgManager) throw new Error('Background tasks are not enabled')
+const bgManager = mastra.backgroundTaskManager;
+if (!bgManager) throw new Error('Background tasks are not enabled');
 
-const controller = new AbortController()
-const stream = bgManager.stream({ abortSignal: controller.signal })
+const controller = new AbortController();
+const stream = bgManager.stream({ abortSignal: controller.signal });
 
 for await (const chunk of stream) {
   switch (chunk.type) {
     case 'background-task-running':
-      console.log('started', chunk.payload.taskId, chunk.payload.toolName)
-      break
+      console.log('started', chunk.payload.taskId, chunk.payload.toolName);
+      break;
     case 'background-task-completed':
-      console.log('done', chunk.payload.taskId, chunk.payload.result)
-      break
+      console.log('done', chunk.payload.taskId, chunk.payload.result);
+      break;
     case 'background-task-failed':
-      console.error('failed', chunk.payload.taskId, chunk.payload.error)
-      break
+      console.error('failed', chunk.payload.taskId, chunk.payload.error);
+      break;
   }
 }
 ```

package/.docs/docs/harness/signals.md

@@ -318,6 +318,45 @@ Use `createNotificationInboxTool()` to give agents one tool for inbox actions in
 
 `sendNotificationSignal()` requires a storage domain with `notifications` support. Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
+## Cross-agent connections in Mastra Code
+
+Cross-agent communication is experimental and off by default. Enable it in Mastra Code with the `/settings` toggle "Experimental cross-agent communication" and restart. Embedded clients can set `crossAgentSignals: true` when calling `createMastraCode()`. The setting enables thread ownership advertisements and peer discovery. It also makes the agent connection tools available. It doesn't affect the pub/sub transport itself.
+
+```typescript
+import { createMastraCode } from 'mastracode'
+
+const mastraCode = await createMastraCode({
+  crossAgentSignals: true,
+})
+```
+
+Mastra Code can use notification signals to communicate between agent threads. A peer is an exact `{ agentId, resourceId, threadId }` endpoint. Discovery is a point-in-time advertisement that the exact endpoint is available now. It isn't a durable connection or a guarantee that delivery will succeed.
+
+`agent_connections_list` returns one `peers` collection. Each peer includes:
+
+- `relationship`: `none` or `saved`. This is the authoritative durable state for the current sender thread.
+- `presence`: `advertised` or `absent`. This reflects the current discovery pass.
+- `displayStatus`: A derived, presentational value: `discovered`, `connected`, or `saved`.
+- `canAttemptSend`: `true` only when the peer is both saved and currently advertised.
+
+The displayed statuses mean:
+
+| Status         | Meaning                                                     | Can attempt a send? |
+| -------------- | ----------------------------------------------------------- | ------------------- |
+| `[discovered]` | Advertised now, but not saved by the current sender thread. | No                  |
+| `[connected]`  | Saved by the current sender thread and advertised now.      | Yes                 |
+| `[saved]`      | Saved by the current sender thread, but not advertised now. | No                  |
+
+Use the connection tools for distinct operations:
+
+- `agent_connect` saves a freshly discovered exact peer in the current sender thread.
+- `agent_disconnect` removes a saved peer from the current sender thread. The peer doesn't need to be currently advertised, and repeated disconnects are safe.
+- `agent_signal_send` requires the exact peer to remain saved and freshly advertised at send time. A previously discovered or recently seen peer that's absent from the current discovery pass isn't sendable.
+
+Saved connections remain in the sender thread until explicitly disconnected. Every send independently refreshes discovery and verifies the exact endpoint before routing begins. A saved connection therefore records collaboration intent. It doesn't indicate current presence.
+
+After a send attempt reaches Core routing, the routing result is authoritative. The result can be `wake`, `deliver`, `persist`, `blocked`, or `discard`, depending on the target thread and notification policy. A send that isn't acknowledged by the advertised thread owner returns an error and doesn't consume its `messageId`, so the sender can retry it.
+
 ## Distributed and serverless deployments
 
 Signals coordinate runs through a pub/sub backend. When a signal arrives on a backend that implements `LeaseProvider`, Mastra acquires a lease on the target thread so a single process owns the conversation at a time, then either wakes the agent or routes the input into the running loop. Backends without leasing fall back to a no-op that always grants ownership, which is fine in a single process but not across instances.

package/.docs/docs/index.md

@@ -74,7 +74,7 @@ Short list of known model IDs are:
 
 Go to <https://mastra.ai/models> for a full list of supported models.
 
-Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
+Add a tool to an agent by importing the tool and passing it to the agent constructor as a tools object.
 
 Example:
 

package/.docs/docs/memory/message-history.md

@@ -122,6 +122,8 @@ You can use this history in two ways:
 - **Automatic inclusion**: Mastra automatically includes recent messages in the context window. The default of 10 messages keeps agents grounded in the conversation. Adjust it with `lastMessages` when needed.
 - [**Manual querying**](#querying): For more control, query threads and messages directly with `recall()`. Use the results to choose which memories enter the context window or to render conversation history in your UI.
 
+> **Note:** `lastMessages` counts every stored message, including tool calls, tool results, and [signals](https://mastra.ai/docs/harness/signals) of any kind, so a single turn can add several messages to the count. The window also slides forward on every request: once a thread grows past the limit, the oldest message leaves context on each turn, which changes the start of the prompt and invalidates the provider prompt cache. For long-running conversations, use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps the prompt prefix stable.
+
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
 ## Thread title generation
@@ -232,7 +234,7 @@ const thread = await memory.getThreadById({ threadId: 'thread-123' })
 
 Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination and [semantic search](https://mastra.ai/docs/memory/semantic-recall), with optional date filtering.
 
-Basic recall returns all messages from a thread:
+Fetch a thread's history without pagination. Recall hides reminder signals by default; pass `hideSignals: false` to include them, `true` to hide all recognized signals, or an array to omit selected types. See [signal visibility and compatibility](https://mastra.ai/reference/memory/recall) for matching rules and precedence.
 
 ```typescript
 const { messages } = await memory.recall({
@@ -343,7 +345,9 @@ const { thread, clonedMessages } = await memory.cloneThread({
 
 You can filter cloned messages by count or date range and specify custom thread IDs. Utility methods are also available to inspect clone relationships.
 
-See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread) and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.
+If you don't need the copied messages returned, for example when forking a long thread, use `copyThread()`. It never returns message payloads, and on LibSQL and PostgreSQL the rows are copied inside the database. When semantic recall is enabled, the copied messages are still read back in batches to generate embeddings.
+
+See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread), [`copyThread()`](https://mastra.ai/reference/memory/copyThread), and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.
 
 ## Deleting messages
 

package/.docs/docs/subagents.md

@@ -240,6 +240,31 @@ await parentAgent.generate('Research AI trends', {
 })
 ```
 
+### Reusing an earlier subagent result
+
+By default, subagent results reach the parent agent as tool results, which are stripped from the context forwarded to later subagents. The parent agent must restate an earlier result in the next delegation prompt, which costs tokens and loses detail.
+
+Set `enableResultReferences` to let a later delegation reuse an earlier result verbatim:
+
+```typescript
+await parentAgent.generate('Find and fix the token refresh bug', {
+  delegation: {
+    enableResultReferences: true,
+  },
+})
+```
+
+When enabled:
+
+- Each successful, non-empty subagent result gets a reference ID such as `explorer-1`. The parent agent's model sees it as a `[ref: explorer-1]` line after the subagent's text.
+- The delegation tools gain a `contextFromRefs` input. The parent agent can pass earlier IDs, either as strings (`["explorer-1"]`) or as objects with an optional label and note (`[{ ref: "explorer-1", as: "investigation", note: "bug location" }]`).
+- The referenced text is inserted before the delegation prompt, each result in its own labeled block, exactly as the earlier subagent produced it. `onDelegationStart` and `messageFilter` receive the expanded prompt.
+- If `onDelegationComplete` returns `resultText`, the replaced text is what later delegations receive.
+
+References are held in memory for a single parent agent run and aren't persisted. Rejected, failed, empty, and background-task delegations don't receive a reference ID. Unknown IDs are skipped with a warning and the delegation continues.
+
+Referenced text is output from another agent. Each block uses a fresh, unpredictable tag and tells the receiving subagent to treat the contents as data, but if subagents handle untrusted input, add your own checks in `onDelegationStart` or through processors.
+
 ## Iteration monitoring
 
 `onIterationComplete` is called after each iteration of the parent agent's loop. Use it to monitor execution or guide the next iteration. You can also stop execution early.

package/.docs/integrations/agentic-ui/ai-sdk-ui.md

@@ -1362,6 +1362,11 @@ export function NestedAgentChat() {
                 <div key={index} className="nested-agent">
                   <strong>Nested Agent: {id}</strong>
                   {data.text && <p>{data.text}</p>}
+                  {data.toolErrors?.map(toolError => (
+                    <p key={toolError.toolCallId} className="nested-agent-error">
+                      {toolError.toolName} failed: {toolError.errorText}
+                    </p>
+                  ))}
                 </div>
               )
             }
@@ -1388,6 +1393,8 @@ Key points:
 - Piping `fullStream` to `context.writer` creates `data-tool-agent` parts
 - Read `data-tool-agent-step` when you need the full payload for the nested step that finished
 - The `AgentDataPart` has `id` (on the part) and `data.text` (the current nested-agent text snapshot)
+- A tool that throws inside the nested agent is reported in `data.toolErrors`, each entry `{ toolCallId, toolName, args?, errorText, providerExecuted? }`. `errorText` is a JSON-safe string, so the failure survives serialization to the client instead of arriving as `{}`
+- `toolErrors` resets at each nested step boundary, like `toolCalls` and `toolResults`. For a finished step, read it from `data-tool-agent-step` (`data.step.toolErrors`) or from `data.steps[]` on the final snapshot
 - The tool still returns its own output after the stream completes
 
 For a complete implementation, see the [tool-nested-streams example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/tool-nested-streams.tsx) in UI Dojo.

package/.docs/integrations/file-storage/amazon-s3.md

@@ -111,7 +111,13 @@ const filesystem = new S3Filesystem({
 })
 ```
 
-Provider functions only apply to `S3Filesystem` API calls. When mounting the filesystem into an E2B sandbox, mount configuration only supports static `accessKeyId`, `secretAccessKey`, and `sessionToken` values, so credential refresh must be handled outside the mount.
+Provider functions only apply to `S3Filesystem` API calls. When mounting the filesystem into an E2B or Daytona sandbox, mount configuration only supports static `accessKeyId`, `secretAccessKey`, and `sessionToken` values, so credential refresh must be handled outside the mount. See [temporary credentials in Daytona](https://mastra.ai/integrations/sandboxes/daytona) for mount lifetime and isolation requirements.
+
+### Prefix-scoped permissions
+
+When `prefix` is set, initialization calls `ListObjectsV2` with the normalized prefix, including its trailing `/`, and `MaxKeys: 1`. Credentials must permit listing that prefix. Without a prefix, initialization uses `HeadBucket`. These checks verify access, not whether a directory exists.
+
+The prefix limits which keys the filesystem addresses; it isn't an authorization boundary. For isolation, use credentials whose storage-provider policy restricts access to that prefix. Keep parent credentials on your backend. Read and write permissions alone aren't sufficient for prefixed filesystem initialization.
 
 ### Cloudflare R2
 

package/.docs/integrations/file-storage/archil.md

@@ -4,7 +4,7 @@
 
 # Archil
 
-Stores files on [Archil](https://docs.archil.com) elastic, serverless disks. Combines an S3-compatible object API for fast reads/writes with `exec()` for POSIX shell operations and `grep()` for parallel server-side search. For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+Stores files on [Archil](https://docs.archil.com) elastic, serverless disks. Combines an S3-compatible object API for fast reads/writes with `exec()` for POSIX shell operations and `diskGrep()` for parallel server-side search. For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
 
 ## Installation
 
@@ -173,12 +173,12 @@ const result = await filesystem.exec('ls -la /data')
 // { exitCode: 0, stdout: '...', stderr: '' }
 ```
 
-#### `grep(options)`
+#### `diskGrep(options)`
 
 Run a parallel server-side search across files on the disk.
 
 ```typescript
-const results = await filesystem.grep({
+const results = await filesystem.diskGrep({
   directory: '/logs',
   pattern: 'ERROR',
   recursive: true,

package/.docs/integrations/frameworks/electron.md

@@ -430,7 +430,7 @@ export default function App(): React.JSX.Element {
 }
 ```
 
-This connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `/chat/weather-agent` endpoint, sending propmts there and streaming the response back in chunks.
+This connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `/chat/weather-agent` endpoint, sending prompts there and streaming the response back in chunks.
 
 ## Test your agent
 

package/.docs/integrations/sandboxes/cloudflare-sandbox.md

@@ -82,6 +82,8 @@ const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
 
 Relative paths are resolved under `/workspace`. Absolute paths must also resolve within `/workspace`. Each file is sent as its own bridge request, and the bridge caps a single file at 32 MiB.
 
+The Cloudflare sandbox cannot set per-file permissions, so a `writeFiles` call that includes a `mode` is rejected rather than silently ignored.
+
 ```typescript
 await workspace.sandbox?.writeFiles?.([
   { path: 'src/index.ts', content: "console.log('hello')\n" },

package/.docs/integrations/sandboxes/daytona.md

@@ -200,6 +200,39 @@ const workspace = new Workspace({
 
 When the workspace starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at `/s3-data` and `/gcs-data` as if they were local directories.
 
+#### Temporary S3 credentials
+
+Pass all three credential values to `S3Filesystem` when using temporary credentials. Daytona forwards the session token to s3fs:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { DaytonaSandbox } from '@mastra/daytona'
+import { S3Filesystem } from '@mastra/s3'
+
+const workspace = new Workspace({
+  mounts: {
+    '/s3-data': new S3Filesystem({
+      bucket: process.env.S3_BUCKET!,
+      region: process.env.S3_REGION ?? 'us-east-1',
+      endpoint: process.env.S3_ENDPOINT,
+      prefix: 'resource-123/thread-456/',
+      accessKeyId: process.env.SCOPED_S3_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.SCOPED_S3_SECRET_ACCESS_KEY!,
+      sessionToken: process.env.SCOPED_S3_SESSION_TOKEN!,
+    }),
+  },
+  sandbox: new DaytonaSandbox({ language: 'python', ephemeral: true }),
+})
+```
+
+Before starting the workspace, obtain credentials from your storage provider that authorize only the intended prefix. Credential issuance is provider-specific; Mastra doesn't mint or restrict credentials. A `prefix` selects a directory but doesn't enforce authorization. Authenticate each request, authorize its resource and thread, and use separate sandboxes for separate security scopes.
+
+Temporary credentials are loaded when the mount starts and aren't automatically refreshed. Host-side credential provider functions don't refresh the mount. Keep runs within the credential lifetime and create a new sandbox with fresh credentials for later runs. Reconnecting to a sandbox doesn't renew its credentials.
+
+Credentials are uploaded into owner-only files inside private directories. After launching s3fs, Daytona removes the temporary-credential staging file and directory. The daemon retains the credentials in its environment, which sandbox code running as the same user or root can still read. Never supply broader credentials than the sandbox needs. Mounts using long-lived credentials retain their password files while s3fs needs them. Unmount and reconnect cleanup remove those files after verifying that the daemon has exited. If a daemon is still active, including after a mount is moved aside, or its status can't be checked, the files are retained and a warning is logged. Cleanup on a later unmount of the same path retries removal; deleting the sandbox removes any remaining files.
+
+Prefixed filesystems require permission to list their prefix during initialization. With s3fs, a prefixed mount may also require a zero-byte object at the exact `<prefix>/` key. Provision that directory marker before mounting. After launching s3fs, Daytona checks the mounted directory's metadata without listing its contents, with a 15-second timeout and forced termination after another 5 seconds. A failed check reports a mount failure. Cleanup attempts to unmount the failed mount, moving a stuck mount aside if necessary to free the original path for retry. Moved stale mounts may remain until sandbox deletion. This startup check doesn't guarantee read or write access to individual files or ongoing daemon health; verify a read and write through the mounted path.
+
 #### Via `sandbox.mount()`
 
 Mount manually at any point after the sandbox has started:

package/.docs/integrations/sandboxes/docker.md

@@ -162,6 +162,19 @@ const sandbox = new DockerSandbox({
 })
 ```
 
+## Write files
+
+Upload multiple files in one call with `writeFiles`. Relative paths resolve under the working directory. Set an optional per-file `mode` to control POSIX permissions; it must be an integer between `0o001` and `0o777`. When `mode` is omitted, new files are created with `0644`.
+
+```typescript
+await sandbox.writeFiles([
+  { path: 'src/index.js', content: "console.log('hello')\n" },
+  { path: 'run.sh', content: '#!/bin/sh\n', mode: 0o755 },
+])
+```
+
+Docker is the only built-in sandbox that applies an explicit `mode`. Providers that cannot honor per-file permissions (Vercel, E2B, Daytona, Cloudflare) reject a `writeFiles` call that includes a `mode` instead of silently dropping it.
+
 ## Bind mounts
 
 Mount host directories into the container using the `volumes` option:

package/.docs/integrations/voice/livekit.md

@@ -205,6 +205,28 @@ export default createLiveKitWorker({
 
 `configuration.stt` works the same way for per-call transcription, for example a different transcription model or language per tenant. The greeting has a matching per-call form: `configuration.greeting.text` accepts a resolver with the same call context, so one worker can open with each tenant's own phrasing.
 
+### Per-call turn detection
+
+LiveKit's `TurnDetector` classes read the job's inference executor when constructed, so they can only be created inside a LiveKit job, not at module scope where the worker options live. To use one, set the `configuration.turnDetection` resolver. It runs once per call with the same call context as `configuration.stt` and returns anything the top-level `turnDetection` option accepts. Return `undefined` to fall back to the top-level option.
+
+```typescript
+import { turnDetector } from '@livekit/agents-plugin-livekit'
+
+export default createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  turnDetection: 'multilingual',
+  configuration: {
+    // Constructed inside the job, where the inference executor is available.
+    turnDetection: () => new turnDetector.MultilingualModel(0.2),
+  },
+})
+```
+
+The semantic model's inference runners must be registered before the agent server boots, so when this resolver is set the worker imports `@livekit/agents-plugin-livekit` up front. Keep the top-level `turnDetection` set to `'multilingual'` or `'english'` to pre-register only that model; otherwise both stay available.
+
 ### Memory and threads
 
 When the resolved Mastra agent has memory configured, each call becomes one memory thread:
@@ -539,7 +561,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 **vad** (`VAD | 'silero' | false`): Voice activity detection. 'silero' loads the Silero VAD from @livekit/agents-plugin-silero during prewarm. Pass an instance to bring your own, or false to disable. (Default: `'silero'`)
 
-**turnDetection** (`'multilingual' | 'english' | TurnDetectionMode`): End-of-turn detection. 'multilingual' and 'english' load LiveKit's semantic turn detector from @livekit/agents-plugin-livekit. Other values such as 'vad', 'stt', or 'manual' pass through.
+**turnDetection** (`'multilingual' | 'english' | TurnDetectionMode`): End-of-turn detection. 'multilingual' and 'english' load LiveKit's semantic turn detector from @livekit/agents-plugin-livekit. Other values such as 'vad', 'stt', or 'manual' pass through. To construct a TurnDetector instance per call, set the configuration.turnDetection resolver — it takes precedence, with this option as the fallback.
 
 **turnHandling** (`Partial<TurnHandlingOptions>`): Turn handling tuning: endpointing delays, interruption sensitivity, preemptive generation. The worker disables preemptiveGeneration unless set here — each preemptive attempt re-runs the Mastra agent and persists partial user and assistant messages unless memory.options.readOnly is set.
 
@@ -551,7 +573,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 **onTurnComplete** (`(ctx: VoiceTurnCompleteContext) => void | Promise<void>`): Called once per turn after the reply finished streaming to text-to-speech. Runs off the audio path and is not awaited. The context carries the produced reply (text, toolCalls, interrupted, usage) and the resolved memory mapping.
 
-**configuration** (`LiveKitWorkerConfiguration`): Grouped conversation and compliance configuration: the opening greeting and AI disclosure, consent requirements, agent-initiated hang-up, and per-call STT/TTS selection.
+**configuration** (`LiveKitWorkerConfiguration`): Grouped conversation and compliance configuration: the opening greeting and AI disclosure, consent requirements, agent-initiated hang-up, and per-call STT/TTS/turn detection selection.
 
 **configuration.greeting** (`GreetingConfiguration`): The opening greeting and AI disclosure: text (a fixed string or a per-call resolver for per-tenant greetings), allowInterruptions, awaitPlayout, persist, and periodic re-disclosure via repeatEvery and repeatText.
 
@@ -563,6 +585,8 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 **configuration.tts** (`(context: VoiceCallContext) => TTS | string | undefined`): Per-call text-to-speech: a resolver invoked once per call (post-connect) with { metadata, requestContext, roomName, ctx }, returning anything the top-level tts option accepts — one voice or language per tenant. Return undefined to fall back to the top-level tts. Cache plugin instances across calls.
 
+**configuration.turnDetection** (`(context: VoiceCallContext) => TurnDetectionMode | undefined`): Per-call end-of-turn detection: a resolver invoked once per call (post-connect, inside the LiveKit job) with { metadata, requestContext, roomName, ctx }, returning anything the top-level turnDetection option accepts. Use it to construct LiveKit TurnDetector instances, which need the job's inference executor. Return undefined to fall back to the top-level turnDetection.
+
 **greeting** (`string`): Static greeting spoken when the session starts. Deprecated: prefer configuration.greeting.text.
 
 **persistGreeting** (`boolean`): Save the spoken greeting to the memory thread as an assistant message, making the saved thread a faithful call transcript. Only applies when a greeting is set and memory is enabled. Deprecated: prefer configuration.greeting.persist. (Default: `true`)

package/.docs/models/gateways/merge-gateway.md

@@ -4,7 +4,7 @@
 
 # ![Merge Gateway logo](https://models.dev/logos/merge-gateway.svg)Merge Gateway
 
-Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 182 models through Mastra's model router.
+Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 187 models through Mastra's model router.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -67,6 +67,7 @@ ANTHROPIC_API_KEY=ant-...
 | `deepseek/deepseek-v3.1`                         |
 | `deepseek/deepseek-v3.2`                         |
 | `deepseek/deepseek-v4-flash`                     |
+| `deepseek/deepseek-v4-flash-0423`                |
 | `deepseek/deepseek-v4-flash-0731`                |
 | `deepseek/deepseek-v4-flash-0731-fast`           |
 | `deepseek/deepseek-v4-pro`                       |
@@ -94,6 +95,9 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemini-embedding-001`                    |
 | `google/gemini-flash-latest`                     |
 | `google/gemini-flash-lite-latest`                |
+| `google/gemma-3-12b-it`                          |
+| `google/gemma-3-27b-it`                          |
+| `google/gemma-3-4b-it`                           |
 | `google/gemma-4-26b-a4b-it`                      |
 | `google/gemma-4-31b-it`                          |
 | `meta/llama-3.1-70b-instruct`                    |
@@ -160,6 +164,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-oss-120b`                            |
 | `openai/gpt-oss-20b`                             |
 | `openai/gpt-oss-safeguard-120b`                  |
+| `openai/gpt-oss-safeguard-20b`                   |
 | `openai/o1`                                      |
 | `openai/o3`                                      |
 | `openai/o3-mini`                                 |

package/.docs/models/gateways/netlify.md

@@ -4,7 +4,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 252 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 253 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -161,6 +161,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/inclusionai/ling-3.0-flash-fin`                           |
 | `openrouter/inclusionai/ling-3.0-flash-fin:free`                      |
 | `openrouter/inclusionai/ling-3.0-flash-sante:free`                    |
+| `openrouter/inclusionai/ling-3.0-flash-vl`                            |
 | `openrouter/inclusionai/ling-3.0-flash-vl:free`                       |
 | `openrouter/mancer/weaver`                                            |
 | `openrouter/meta-llama/llama-3.1-70b-instruct`                        |