@mastra/mcp-docs-server 1.2.19-alpha.0 → 1.2.19-alpha.4

package/.docs/docs/evals/built-in-scorers.md

@@ -22,6 +22,7 @@ These scorers evaluate how correct, truthful, and complete your agent's answers
 - [`tool-call-accuracy`](https://mastra.ai/reference/evals/tool-call-accuracy): Evaluates whether the LLM selects the correct tool from available options (`0-1`, higher is better)
 - [`trajectory-accuracy`](https://mastra.ai/reference/evals/trajectory-accuracy): Evaluates the expected action sequence for all span types. Covered spans include tool and model activity plus workflow steps (`0-1`, higher is better)
 - [`prompt-alignment`](https://mastra.ai/reference/evals/prompt-alignment): Measures how well agent responses align with user prompt intent, requirements, completeness, and format (`0-1`, higher is better)
+- [`multi-turn-judge`](https://mastra.ai/reference/evals/multi-turn-judge): Grades every assistant turn of a [multi-turn conversation](https://mastra.ai/docs/evals/multi-turn) against a plain-English criterion (`0` or `1`)
 
 ### Context quality
 

package/.docs/docs/evals/multi-turn.md

@@ -35,6 +35,8 @@ const result = await runEvals({
 
 Each turn runs `agent.generate()` with the same thread ID, so the agent sees the full conversation history. Scorers receive the accumulated output messages from all turns.
 
+> **Prebuilt LLM judges grade one turn:** Prebuilt LLM-judge scorers (rubric, answer relevancy, faithfulness, and the others listed in [Scorer compatibility](#scorer-compatibility)) read a single assistant message, so with `inputs` they grade only the last turn's response. For semantic grading across a conversation, use [`createMultiTurnJudgeScorer()`](https://mastra.ai/reference/evals/multi-turn-judge), which grades every assistant turn against one criterion, or per-turn [`turns[].scorers`](#per-turn-assertions-with-turns), where each turn grades its own output.
+
 ## Memory is required for cross-turn recall
 
 Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones, but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent won't recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
@@ -70,6 +72,85 @@ These details matter when writing scorers for multi-turn items:
 - **`run.output` is the accumulated output from every turn.** Output-based scorers: `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar: evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
 - **`run.input` is only the first turn's input.** Scorers that compare input against output (faithfulness, answer relevancy, and other input-relative LLM scorers) only see the first user message, not the full conversation. Prefer output-based checks for multi-turn, or build scorers that read the accumulated `run.output` directly.
 
+### Scorer compatibility
+
+Accumulated output only helps if the scorer reads all of it:
+
+| Scorer                                                                                                                                                                                                                         | What it sees with `inputs`                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| [Quick Checks](https://mastra.ai/docs/evals/quick-checks): `checks.calledTool`, `checks.includes`, `checks.similarity`, `checks.noToolErrors`, and the rest                                                                    | The whole conversation. Tool-call checks count calls across every turn, and text checks search all assistant text |
+| [Multi-turn Judge scorer](https://mastra.ai/reference/evals/multi-turn-judge)                                                                                                                                                  | Every assistant turn, graded together against one plain-English criterion                                         |
+| Prebuilt LLM-judge scorers: rubric, answer relevancy, answer similarity, faithfulness, hallucination, bias, toxicity, context precision, context recall, context relevance, noise sensitivity, prompt alignment, summarization | Only the last assistant message that carries text. Input-relative judges also see only the first turn's input     |
+| Trajectory scorers (`AgentScorerConfig.trajectory`)                                                                                                                                                                            | The last turn's span when traces are available, otherwise tool calls from all accumulated messages                |
+| Custom scorers                                                                                                                                                                                                                 | Whatever they read from `run.output`                                                                              |
+
+### Grading a whole conversation
+
+To judge every turn together, use [`createMultiTurnJudgeScorer()`](https://mastra.ai/reference/evals/multi-turn-judge). It builds a transcript of every assistant turn and asks a judge model whether the conversation satisfies one plain-English criterion, scoring `1` or `0`:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createMultiTurnJudgeScorer } from '@mastra/evals/scorers/prebuilt'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: [
+        "How's the weather in London?",
+        'And Paris?',
+        'Should I pack an umbrella for London?',
+      ],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [
+    {
+      scorer: createMultiTurnJudgeScorer({
+        model: 'anthropic/claude-haiku-4-5',
+        criterion:
+          'The agent provided forecasts for London and Paris, and gave weather-appropriate packing advice.',
+      }),
+      threshold: 1,
+    },
+  ],
+})
+```
+
+To grade something the criterion can't express, write your own scorer that reads the assistant messages out of `run.output`. [`extractAgentResponseMessages()`](https://mastra.ai/reference/evals/scorer-utils) returns the text of each assistant message, in order:
+
+```typescript
+import { createScorer } from '@mastra/core/evals'
+import { extractAgentResponseMessages } from '@mastra/evals/scorers/utils'
+import { z } from 'zod'
+
+export const conversationJudge = createScorer({
+  id: 'conversation-judge',
+  name: 'Conversation Judge',
+  description: 'Grades every assistant turn in a conversation against one criterion',
+  type: 'agent',
+  judge: {
+    model: 'anthropic/claude-haiku-4-5',
+    instructions: 'You grade multi-turn assistant transcripts against a single criterion.',
+  },
+})
+  .analyze({
+    description: 'Judge the transcript as a whole',
+    outputSchema: z.object({ satisfied: z.boolean(), reason: z.string() }),
+    createPrompt: ({ run }) => {
+      const transcript = extractAgentResponseMessages(run.output)
+        .map((text, index) => `Turn ${index + 1}: ${text}`)
+        .join('\n\n')
+
+      return `Grade this conversation:\n\n${transcript}\n\nCriterion: the assistant keeps the forecast consistent across turns.`
+    },
+  })
+  .generateScore(({ results }) => (results.analyzeStepResult?.satisfied ? 1 : 0))
+  .generateReason(({ results }) => results.analyzeStepResult?.reason ?? '')
+```
+
+Pass it to `runEvals` like any other scorer. See [Custom scorers](https://mastra.ai/docs/evals/custom-scorers) for the full `createScorer()` pipeline.
+
 ## Per-turn assertions with `turns`
 
 The `inputs` form scores the **accumulated** output as a whole, a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
@@ -175,4 +256,6 @@ await runEvals({
 
 - [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals): Full API for `runEvals` parameters and returns
 - [Gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Enforce hard requirements and quality thresholds
-- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers
+- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers
+- [Scorer utilities](https://mastra.ai/reference/evals/scorer-utils): Helpers for reading messages out of a scorer run
+- [Multi-turn Judge scorer](https://mastra.ai/reference/evals/multi-turn-judge): LLM judge that grades every assistant turn together

package/.docs/docs/evals/overview.md

@@ -115,15 +115,77 @@ For the step-level `scorers` API, see the [Step class reference](https://mastra.
 
 **Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. Your AI systems remain responsive while live evaluations monitor them.
 
-**Sampling control**: The `sampling.rate` parameter (0-1) controls what percentage of outputs get scored:
+**Sampling control**: The `sampling.rate` parameter (0-1) controls what fraction of outputs get scored:
 
 - `1.0`: Score every single response (100%)
 - `0.5`: Score half of all responses (50%)
 - `0.1`: Score 10% of responses
 - `0.0`: Disable scoring
 
+Sampling is deterministic per trace: the decision is derived from the trace ID, not drawn at random. In practice:
+
+- Scorers configured at the same rate score the same traces, so their scores are comparable on shared traffic.
+- Re-running the same trace produces the same sampling decision, so sampled coverage is reproducible.
+
+When a run has no trace (observability not configured), the decision is derived from the run ID instead. If [trace sampling](https://mastra.ai/docs/observability/tracing/overview) declined the trace, scorers skip that run entirely, so scores aren't created for traces that were never stored.
+
+**Eligibility filters**: The optional `filter` parameter restricts which runs a scorer is eligible for, using a declarative predicate over the run's context. Filters are evaluated before sampling, so `sampling.rate` applies only to runs that match the filter:
+
+```typescript
+export const myAgent = new Agent({
+  // ...
+  scorers: {
+    relevancy: {
+      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+      filter: {
+        op: 'eq',
+        left: { path: 'requestContext.plan' },
+        right: { literal: 'enterprise' },
+      },
+      sampling: { type: 'ratio', rate: 0.1 },
+    },
+  },
+})
+```
+
+This scores 10% of enterprise-plan traffic and none of the rest. To score different segments at different rates, bind the same scorer twice with complementary filters.
+
+Predicates can reference `requestContext.*`, `entity.*`, `entityType`, `source`, `threadId`, `resourceId`, and `projectId`. They support comparisons (`eq`, `ne`, `lt`, `lte`, `gt`, `gte`), membership (`in`, `notIn`), existence (`exists`, `notExists`), truthiness (`truthy`, `falsy`), and boolean composition (`and`, `or`, `not`). A filter that references an unknown root fails at agent construction rather than silently skipping scoring at runtime. Filters are plain JSON, so they're unaffected by durable agent state serialization.
+
+Eligibility filters decide _whether a scorer runs_; to filter _which messages a scorer sees_ once it runs, use [`filterRun()`](https://mastra.ai/reference/evals/filter-run).
+
 **Automatic storage**: All scoring results are automatically stored in the `mastra_scorers` table in your configured database, allowing you to analyze performance trends over time.
 
+## Score persistence
+
+Scores are persisted when the Mastra instance has `storage` configured, and when the scorer is registered on that instance. Registration is what lets Mastra resolve the scorer's metadata (name, description, type) through [`getScorerById()`](https://mastra.ai/reference/core/getScorerById) before writing the score.
+
+Scorers you attach to an agent or a workflow step register themselves. Scorers you pass directly to [`runEvals()`](https://mastra.ai/reference/evals/run-evals), including [Quick Checks](https://mastra.ai/docs/evals/quick-checks), need the `scorers` option on the [`Mastra` class](https://mastra.ai/reference/core/mastra-class):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { checks } from '@mastra/evals/checks'
+import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
+import { myAgent } from './agents/my-agent'
+
+export const mastra = new Mastra({
+  agents: { myAgent },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  scorers: {
+    calledTool: checks.calledTool('get_weather'),
+    includes: checks.includes('Brooklyn'),
+    relevancy: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+  },
+})
+```
+
+The lookup only compares scorer IDs, so a registered instance can be configured differently from the one you evaluate with. Every `checks.calledTool()` instance has the id `check-called-tool`, so registering one covers all of them, whatever tool name you evaluate with.
+
+The arguments still shape the `description` stored alongside each score, which comes from the registered instance, not the one you evaluate with. `checks.calledTool('')` is accepted and persists scores fine, but stores `Checks that "" was called`, so pass a representative value.
+
+Skipping registration doesn't change scoring results, but each save fails with a `Scorer with id <id> not found` warning and the scores never reach the store.
+
 ## Trace evaluations
 
 In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows.

package/.docs/docs/sandbox/filesystem.md

@@ -7,7 +7,7 @@ A filesystem gives an agent tools for reading, writing, listing, and [searching]
 Configure files in two ways:
 
 - [Direct filesystem access](#direct-filesystem-access) uses `filesystem` with one filesystem provider or a [`CompositeFilesystem`](#manual-composition) that you create yourself.
-- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When the workspace also has a static sandbox, Mastra attempts to mount each provider at its configured path inside the sandbox so commands can access the same files. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
+- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When a static sandbox and filesystem provider support mounting, Mastra automatically mounts the provider at its configured path. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
 
 Configure either `filesystem` or `mounts`, not both. Configuring both throws a `WorkspaceError` with the code `INVALID_CONFIG`.
 
@@ -71,7 +71,7 @@ See [Search](https://mastra.ai/docs/sandbox/search) to index the files for keywo
 
 ## Mounts
 
-Use `mounts` when programs inside a sandbox need to access persistent files by path. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
+Use `mounts` when programs inside a sandbox need to access persistent files by path. Mastra creates the mount automatically when the sandbox and filesystem provider support it. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
 
 For example, mount an S3 bucket at `/workspace` inside a Daytona sandbox:
 
@@ -180,7 +180,7 @@ Use manual composition when another part of your application needs the composite
 
 ## Mount availability
 
-File tools and composite routing work without FUSE. Remote sandboxes can use FUSE to make cloud storage visible to commands. `LocalSandbox` uses symlinks instead.
+File tools and composite routing work without a sandbox mount. When a remote sandbox and filesystem provider support mounting, `mounts` automatically uses FUSE to make the files visible to commands. `LocalSandbox` uses symlinks instead.
 
 Built-in sandbox mounting currently includes:
 
@@ -195,27 +195,27 @@ Remote mounts may require `s3fs`, `gcsfuse`, or `blobfuse2` inside the sandbox.
 
 If a sandbox mount is unavailable or fails, the workspace remains usable. File tools continue to access the provider through its SDK, but commands can't see that path. Mastra describes these providers to the agent as available through file tools only.
 
-## Multi-tenant filesystems
+## Filesystems per user or thread
 
 The `filesystem` option accepts a resolver when storage should vary by request, user, role, or tenant:
 
 ```typescript
 const workspace = new Workspace({
   filesystem: ({ requestContext }) => {
-    const tenantId = requestContext.get('tenant-id') as string
+    const userId = requestContext.get('user-id') as string
 
     return new S3Filesystem({
       bucket: process.env.S3_BUCKET!,
       region: process.env.S3_REGION!,
-      prefix: `tenants/${tenantId}`,
+      prefix: `users/${userId}`,
     })
   },
 })
 ```
 
-Each tenant gets its own filesystem view, and file tools resolve the provider from the request context automatically.
+Each user gets a separate filesystem view, and file tools resolve the provider from the request context automatically.
 
-`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/sandbox/overview).
+`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Sandboxes per user or thread](https://mastra.ai/docs/sandbox/overview).
 
 ## Policies and containment
 

package/.docs/docs/sandbox/overview.md

@@ -2,27 +2,27 @@
 
 # Sandboxes and filesystems
 
-A sandbox gives your agent an environment where it can run commands, execute code, install dependencies, and manage processes. Sandboxes can isolate potentially risky agent-run code from your host, and they can also provide a place to run longer-lived or more resource-intensive work outside your application process.
+A sandbox gives your agent an isolated environment where it can run commands, execute code, install dependencies, and manage processes. This lets agents perform work that would be risky, resource-intensive, or impractical to run directly inside your application.
 
-[Filesystems](https://mastra.ai/docs/sandbox/filesystem) give the agent files it can read, write, and [search](https://mastra.ai/docs/sandbox/search). They can provide a knowledge base for your agent, or be shared with a sandbox so commands can work with the same files and keep data beyond the sandbox's lifetime.
+Sandboxes are often temporary, so files created inside them may disappear when the environment stops. A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives the agent a place to read, write, and [search](https://mastra.ai/docs/sandbox/search) files that can outlive the sandbox. You can use one to keep outputs between runs, seed a new sandbox with existing files, or give the agent documents it can search while working. Filesystems also work without a sandbox, for example when an agent only needs a knowledge base or access to files in a service such as Google Drive.
 
 ## When to use sandboxes
 
-Sandboxes work well for:
+Use a sandbox when an agent needs to:
 
-- **Coding agents and software factories**: Clone repositories and run shell, Git, build, or test workflows without giving autonomous agents access to the host system.
-- **Deep research and analysis**: Use specialized libraries to process downloaded PDFs or presentations and produce new artifacts.
-- **Long-running and parallel tasks**: Run work in separate environments without tying it to one request or sharing files and processes.
+- Clone repositories and run shell, Git, build, or test workflows in a separate environment.
+- Process PDFs, presentations, or other files with specialized libraries and produce new artifacts.
+- Run long-lived or parallel work in separate environments with isolated files and processes.
 
 If an agent only needs to read, write, or search files, configure [direct filesystem access](https://mastra.ai/docs/sandbox/filesystem).
 
 ## Quickstart
 
-Give an agent a local sandbox and filesystem:
+Give an agent a local sandbox:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
+import { LocalSandbox, Workspace } from '@mastra/core/workspace'
 
 export const codingAgent = new Agent({
   id: 'coding-agent',
@@ -33,20 +33,15 @@ export const codingAgent = new Agent({
     sandbox: new LocalSandbox({
       workingDirectory: './workspace',
     }),
-    filesystem: new LocalFilesystem({
-      basePath: './workspace',
-    }),
   }),
 })
 
 await codingAgent.generate('List the files in the sandbox directory')
 ```
 
-> **Warning:** `LocalSandbox` is the quickest sandbox to set up, but commands run on the host by default. Enable [native isolation](#localsandbox) whenever possible. For applications exposed to untrusted users, use a remote or container backend with a stronger isolation boundary instead.
-
-To use a different sandbox for each user, tenant, or thread, configure a [sandbox resolver](#multi-tenant-sandboxes) instead.
+> **Warning:** `LocalSandbox` runs commands on the application host by default and isn't isolated or secure. Enable [native isolation](#localsandbox), or use a remote or container sandbox when running untrusted code.
 
-The `LocalSandbox` above is one static instance. Every request and memory thread that uses `codingAgent` shares its files, processes, and lifecycle state. A memory thread doesn't create an isolated sandbox by itself.
+A static sandbox is shared across every request and memory thread that uses the agent. Use a [resolver](#sandboxes-per-user-or-thread) when each user or thread needs a separate environment. See [Lifecycle and persistence](#lifecycle-and-persistence) for sharing and cleanup details.
 
 ## Using the sandbox
 
@@ -74,7 +69,7 @@ const workspace = new Workspace({
 })
 ```
 
-Omitting a tool entry keeps its capability-driven default. Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
+Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
 
 See the [sandbox tools reference](https://mastra.ai/reference/workspace/workspace-class) for all generated tools and the [tool configuration reference](https://mastra.ai/reference/workspace/workspace-class) for approvals, output limits, and hooks.
 
@@ -109,17 +104,12 @@ export const startServerTool = createTool({
 })
 ```
 
-## Supported backends
+## Sandboxes
 
 ### `LocalSandbox`
 
 [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) executes commands on the same machine as your Mastra application. By default, commands run directly on the host with the permissions of the application process.
 
-Enable native isolation to restrict filesystem and network access at the operating-system level:
-
-- **macOS**: Seatbelt (`sandbox-exec`)
-- **Linux**: Bubblewrap (`bwrap`)
-
 ```typescript
 const sandbox = new LocalSandbox({
   workingDirectory: './workspace',
@@ -131,11 +121,13 @@ const sandbox = new LocalSandbox({
 })
 ```
 
-Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system. The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
+Enable native isolation to restrict filesystem and network access at the operating-system level. On macOS, native isolation uses Seatbelt (`sandbox-exec`). On Linux, it uses Bubblewrap (`bwrap`). Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system.
 
-### Other backends
+The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
 
-Use a remote or container backend when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each backend has its own isolation, persistence, networking, and mount behavior:
+### Remote sandboxes
+
+Use a remote or container sandbox when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each sandbox has its own isolation, persistence, networking, and mount behavior:
 
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
@@ -149,47 +141,40 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)
 - [Vercel](https://mastra.ai/integrations/sandboxes/vercel)
 
-If Mastra doesn't support your execution backend, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
+If Mastra doesn't support your sandbox provider, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
 
 ## Filesystem
 
-Each sandbox has a native filesystem that commands can use. Treat it as ephemeral because its contents follow the sandbox's lifecycle.
+Every sandbox has a filesystem for commands. `LocalSandbox` uses the host filesystem, while remote sandboxes have isolated filesystems that are often temporary. For files that need to outlive a sandbox, use external storage.
+
+Mastra filesystems connect agents and sandboxes to provider-backed storage such as Amazon S3, Google Cloud Storage, or Google Drive. Configuring one gives the agent tools to read, write, and search files. When a remote sandbox and provider support mounting, Mastra automatically mounts the storage through Filesystem in Userspace (FUSE). Commands use normal file paths while the provider stores changes outside the sandbox.
 
-To seed a sandbox with files or keep files between runs, give the agent a [filesystem](https://mastra.ai/docs/sandbox/filesystem). Use mounts when sandbox commands need access to the same files.
+See [Filesystem](https://mastra.ai/docs/sandbox/filesystem) for providers, file tools, and mounts.
 
-## Multi-tenant sandboxes
+## Sandboxes per user or thread
 
 Use a **resolver** when each user, tenant, or thread needs a separate sandbox. Set `sandboxCacheKey` to the identity that owns the sandbox so later requests reuse the same live environment.
 
 This example creates and caches one Daytona sandbox per user:
 
 ```typescript
-import type { RequestContext } from '@mastra/core/request-context'
 import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 
-const getUserId = (requestContext: RequestContext) => {
-  const userId = requestContext.get('user-id')
-  if (typeof userId !== 'string' || !userId) {
-    throw new Error('A user ID is required to resolve this sandbox')
-  }
-
-  return userId
-}
-
 const workspace = new Workspace({
   sandbox: async ({ requestContext }) => {
-    const sandbox = new DaytonaSandbox({ id: `user-${getUserId(requestContext)}` })
+    const userId = requestContext.get('user-id') as string
+    const sandbox = new DaytonaSandbox({ id: `user-${userId}` })
     await sandbox.start()
     return sandbox
   },
-  sandboxCacheKey: ({ requestContext }) => getUserId(requestContext),
+  sandboxCacheKey: ({ requestContext }) => requestContext.get('user-id') as string,
 })
 ```
 
 The first request from a user creates the sandbox. Later requests with the same user ID reuse it.
 
-For a sandbox with persistent storage, create the filesystem and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
+For a sandbox with persistent storage, create a [filesystem](https://mastra.ai/docs/sandbox/filesystem) and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
 
 ```typescript
 import { MASTRA_THREAD_ID_KEY, type RequestContext } from '@mastra/core/request-context'
@@ -197,14 +182,8 @@ import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 import { S3Filesystem } from '@mastra/s3'
 
-const getThreadId = (requestContext: RequestContext) => {
-  const threadId = requestContext.get(MASTRA_THREAD_ID_KEY)
-  if (typeof threadId !== 'string' || !threadId) {
-    throw new Error('A memory thread is required to resolve this sandbox')
-  }
-
-  return threadId
-}
+const getThreadId = (requestContext: RequestContext) =>
+  requestContext.get(MASTRA_THREAD_ID_KEY) as string
 
 const createThreadFilesystem = (threadId: string) =>
   new S3Filesystem({
@@ -234,25 +213,13 @@ The first request in a thread runs the resolver and starts the sandbox. Later re
 
 The example mounts the filesystem inside the resolver because static `mounts` can't be combined with a sandbox resolver. Generated tools resolve the filesystem and sandbox from the request context automatically.
 
-### Resolver ownership
-
-You are responsible for every sandbox returned by a resolver. It must be ready to use when returned. Keep track of it and destroy it through your application lifecycle code when it's no longer needed. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
-
-Resolvers are incompatible with `mounts` and [`lsp: true`](https://mastra.ai/docs/sandbox/lsp), because both require a static sandbox during configuration. Using a resolver with `mounts` throws an `INVALID_CONFIG` error. With `lsp: true`, Mastra disables LSP and logs a warning.
+> **Warning:** Your application owns sandboxes returned by a resolver. Destroy them and call `workspace.clearSandboxCache(cacheKey)` when the user, thread, or session ends. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
 
 ### Tool availability
 
-With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it:
-
-```typescript
-const processManager = workspace.sandbox?.processes
-
-if (processManager) {
-  await processManager.spawn('pnpm dev')
-}
-```
+With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it.
 
-With a [resolver-backed sandbox](#multi-tenant-sandboxes), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
+With a [resolver-backed sandbox](#sandboxes-per-user-or-thread), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 
@@ -292,7 +259,7 @@ Who shares a sandbox depends on where you configure it and whether you use a res
 | Resource-scoped resolver   | The resolver caches one sandbox for each resource ID.                                                                               |
 | Thread-scoped resolver     | A memory thread keeps its sandbox across requests in that thread.                                                                   |
 
-A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Multi-tenant sandboxes](#multi-tenant-sandboxes).
+A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Sandboxes per user or thread](#sandboxes-per-user-or-thread).
 
 ### Start
 

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

@@ -2,7 +2,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 174 models through Mastra's model router.
+Merge Gateway aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 175 models through Mastra's model router.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -66,6 +66,7 @@ ANTHROPIC_API_KEY=ant-...
 | `deepseek/deepseek-v4-flash`                     |
 | `deepseek/deepseek-v4-flash-0731`                |
 | `deepseek/deepseek-v4-pro`                       |
+| `deepseek/deepseek-v4-pro-0423`                  |
 | `deepseek/deepseek-v4-pro-0813`                  |
 | `google/gemini-2.5-computer-use-preview-10-2025` |
 | `google/gemini-2.5-flash`                        |

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

@@ -2,7 +2,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 228 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 227 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -120,7 +120,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/bytedance-seed/seed-2.0-mini`                             |
 | `openrouter/bytedance/ui-tars-1.5-7b`                                 |
 | `openrouter/cognitivecomputations/dolphin-mistral-24b-venice-edition` |
-| `openrouter/deepcogito/cogito-v2.1-671b`                              |
 | `openrouter/deepseek/deepseek-chat`                                   |
 | `openrouter/deepseek/deepseek-chat-v3-0324`                           |
 | `openrouter/deepseek/deepseek-chat-v3.1`                              |

package/.docs/models/gateways/openrouter.md

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 356 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 360 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -92,7 +92,6 @@ ANTHROPIC_API_KEY=ant-...
 | `cohere/command-r-plus-08-2024`                            |
 | `cohere/command-r7b-12-2024`                               |
 | `cohere/north-mini-code:free`                              |
-| `deepcogito/cogito-v2.1-671b`                              |
 | `deepseek/deepseek-chat`                                   |
 | `deepseek/deepseek-chat-v3-0324`                           |
 | `deepseek/deepseek-chat-v3.1`                              |
@@ -104,6 +103,7 @@ ANTHROPIC_API_KEY=ant-...
 | `deepseek/deepseek-v3.2-exp`                               |
 | `deepseek/deepseek-v4-flash`                               |
 | `deepseek/deepseek-v4-flash-0731`                          |
+| `deepseek/deepseek-v4-flash-vision-exp`                    |
 | `deepseek/deepseek-v4-pro`                                 |
 | `deepseek/deepseek-v4-pro-0813`                            |
 | `dots-studio/dots-3-note-preview:free`                     |
@@ -150,6 +150,7 @@ ANTHROPIC_API_KEY=ant-...
 | `kwaipilot/kat-coder-pro-v2`                               |
 | `kwaipilot/kat-coder-pro-v2.5`                             |
 | `liquid/lfm-2.5-2.6b:free`                                 |
+| `mancer/weaver`                                            |
 | `meituan/longcat-2.0`                                      |
 | `meta-llama/llama-3.1-70b-instruct`                        |
 | `meta-llama/llama-3.1-8b-instruct`                         |
@@ -162,6 +163,7 @@ ANTHROPIC_API_KEY=ant-...
 | `meta/muse-glimmer-30b`                                    |
 | `meta/muse-spark-1.1`                                      |
 | `meta/muse-spark-1.2`                                      |
+| `meta/muse-spark-1.2-contributor`                          |
 | `microsoft/phi-4`                                          |
 | `microsoft/wizardlm-2-8x22b`                               |
 | `minimax/minimax-01`                                       |
@@ -366,6 +368,8 @@ ANTHROPIC_API_KEY=ant-...
 | `thedrummer/unslopnemo-12b`                                |
 | `thinkingmachines/inkling`                                 |
 | `thinkingmachines/inkling-small`                           |
+| `thinkingmachines/inkling-small:free`                      |
+| `thinkingmachines/inkling:free`                            |
 | `undi95/remm-slerp-l2-13b`                                 |
 | `upstage/solar-pro-3`                                      |
 | `upstage/solar-pro4`                                       |

package/.docs/models/gateways/vercel.md

@@ -2,7 +2,7 @@
 
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 347 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 351 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -133,6 +133,7 @@ ANTHROPIC_API_KEY=ant-...
 | `deepseek/deepseek-v3.2-thinking`         |
 | `deepseek/deepseek-v4-flash`              |
 | `deepseek/deepseek-v4-flash-0731`         |
+| `deepseek/deepseek-v4-flash-vision-exp`   |
 | `deepseek/deepseek-v4-pro`                |
 | `deepseek/deepseek-v4-pro-0813`           |
 | `fish-audio/s1`                           |
@@ -352,6 +353,9 @@ ANTHROPIC_API_KEY=ant-...
 | `spacexai/grok-voice-think-fast-2.0`      |
 | `stepfun/step-3.5-flash`                  |
 | `stepfun/step-3.7-flash`                  |
+| `tencent/hy-mt2-lite`                     |
+| `tencent/hy-mt2-plus`                     |
+| `tencent/hy-mt2-pro`                      |
 | `tencent/hy3`                             |
 | `thinkingmachines/inkling`                |
 | `thinkingmachines/inkling-small`          |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6740 models from 180 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6767 models from 180 providers through a single API.
 
 ## Features