@mastra/mcp-docs-server 1.1.44 → 1.1.45-alpha.0

package/.docs/docs/workspace/filesystem.md

@@ -121,7 +121,7 @@ const agent = new Agent({
 })
 ```
 
-Each request resolves its own filesystem at tool execution time:
+Each request resolves its own filesystem for workspace tools and workspace instructions:
 
 ```typescript
 import { RequestContext } from '@mastra/core/request-context'
@@ -135,6 +135,8 @@ const viewerCtx = new RequestContext([['agent-role', 'viewer']])
 await agent.generate('Read info.txt', { requestContext: viewerCtx })
 ```
 
+Workspace instructions use the same `requestContext`, so the agent sees the filesystem context for the resolved provider.
+
 The resolver can also be asynchronous, for example to look up configuration from a database:
 
 ```typescript

package/.docs/docs/workspace/overview.md

@@ -171,6 +171,23 @@ const workspace = new Workspace({
 
 One workspace instance serves all requests. The resolver runs at tool execution time, so each request gets its own filesystem. See [dynamic filesystem](https://mastra.ai/docs/workspace/filesystem) for details.
 
+### Dynamic sandbox (per-request)
+
+Pass a resolver function to `sandbox` to return a different sandbox per request. This is useful for multi-tenant deployments where each user or role needs an isolated working directory or different execution permissions.
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => {
+    const userId = requestContext.get('user-id') as string
+    return new LocalSandbox({
+      workingDirectory: `/workspaces/${userId}`,
+    })
+  },
+})
+```
+
+The resolver is incompatible with `mounts` and `lsp: true`, since both require a concrete sandbox instance at construction time. See [dynamic sandbox](https://mastra.ai/docs/workspace/sandbox) for details.
+
 ### Which pattern should I use?
 
 | Scenario                                                  | Pattern                                               |
@@ -181,6 +198,7 @@ One workspace instance serves all requests. The resolver runs at tool execution
 | Agent reads/writes files, no command execution needed     | `filesystem` only                                     |
 | Agent runs commands, no file tools needed                 | `sandbox` only                                        |
 | Multi-role or multi-tenant agent with per-request storage | `filesystem` with resolver function                   |
+| Multi-tenant agent with per-request execution scope       | `sandbox` with resolver function                      |
 
 ## Tool configuration
 

package/.docs/docs/workspace/sandbox.md

@@ -52,6 +52,109 @@ const response = await agent.generate('Run `ls -la` in the workspace directory')
 
 See [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox) for configuration options including environment isolation and native OS sandboxing.
 
+## Dynamic sandbox
+
+The `sandbox` option accepts a resolver function instead of a static instance. The resolver receives `requestContext` and returns a sandbox per request, allowing a single workspace to serve different sandboxes based on the caller's identity, role, or tenant.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => {
+    const userId = requestContext.get('user-id') as string
+    return new LocalSandbox({
+      workingDirectory: `/workspaces/${userId}`,
+    })
+  },
+})
+
+const agent = new Agent({
+  id: 'multi-tenant-agent',
+  model: 'your-provider/your-model',
+  workspace,
+})
+```
+
+Each request resolves its own sandbox at tool execution time:
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+// User Alice — commands run in /workspaces/alice
+const aliceCtx = new RequestContext([['user-id', 'alice']])
+await agent.generate('List files in cwd', { requestContext: aliceCtx })
+
+// User Bob — commands run in /workspaces/bob
+const bobCtx = new RequestContext([['user-id', 'bob']])
+await agent.generate('List files in cwd', { requestContext: bobCtx })
+```
+
+By default, workspace instructions describe the dynamic sandbox with stable placeholder text. See [Workspace instructions](#workspace-instructions) to include concrete per-request details.
+
+The resolver can also be asynchronous — for example to look up tenant configuration from a database:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: async ({ requestContext }) => {
+    const tenant = await db.getTenant(requestContext.get('tenant-id'))
+    return new LocalSandbox({ workingDirectory: tenant.workspacePath })
+  },
+})
+```
+
+### Lifecycle ownership
+
+When the sandbox is a static instance, `workspace.init()` calls its `start()` method and `workspace.destroy()` calls its `destroy()` method. With a resolver, the workspace has no instance to manage at construction time — the caller owns the returned sandbox's lifecycle.
+
+The resolver must return a sandbox that is ready to use, either already started or able to handle calls without explicit startup. The caller also owns cleanup timing for returned sandboxes. Cleanup might happen per request, per tenant, per user, or as part of a long-lived sandbox pool; `workspace.destroy()` does not destroy resolver-returned sandboxes.
+
+> **Note:** `sandbox` resolvers are incompatible with `mounts` and `lsp: true`. Both require a concrete sandbox instance at construction time, so combining them with a resolver throws an `INVALID_CONFIG` error (for `mounts`) or disables LSP with a warning (for `lsp: true`).
+
+### Tool registration
+
+With a static sandbox, the workspace inspects the instance to decide which tools to register. With a resolver, the workspace assumes full capabilities and registers `execute_command` (with `background` support), `get_process_output`, and `kill_process`. If the resolved sandbox does not implement a capability, the runtime throws a clear `SandboxFeatureNotSupportedError`.
+
+### Background process continuity
+
+Background processes can outlive a single tool call, so `get_process_output` and `kill_process` must reach the same sandbox that started the process. By default, a resolved sandbox is cached per request. For continuity across follow-up requests, such as a later conversation turn, set `sandboxCacheKey` to a stable identifier. The resolved sandbox is then cached by that key instead of by request:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
+  sandboxCacheKey: ({ requestContext }) => requestContext.get('thread-id') as string,
+})
+```
+
+Without a `sandboxCacheKey`, the resolver must return the same sandbox itself for follow-up calls that share a tenant, user, or session.
+
+When a cached sandbox is no longer needed, destroy the sandbox in your own lifecycle code and call `workspace.clearSandboxCache(cacheKey)` to drop the workspace cache entry. Call `workspace.clearSandboxCache()` to clear all keyed sandbox entries.
+
+### Workspace instructions
+
+Workspace instructions describe the environment in the agent's system message. With a sandbox resolver, the workspace does not call the resolver to build these instructions. It emits stable placeholder text, so constructing the prompt never provisions a caller-owned sandbox and the system message stays consistent across requests, which keeps prompt caching effective.
+
+To include concrete per-request sandbox details, set `instructions.dynamicSandbox` to `'resolve'`:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
+  instructions: { dynamicSandbox: 'resolve' },
+})
+```
+
+`'resolve'` calls the resolver on every request, which may provision the sandbox and makes the system message request-specific. Pass a function instead to return custom text from `requestContext` without resolving the sandbox:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
+  instructions: {
+    dynamicSandbox: ({ requestContext }) =>
+      `Sandbox scoped to tenant ${requestContext.get('tenant-id')}.`,
+  },
+})
+```
+
 ## Agent tools
 
 When you configure a sandbox on a workspace, agents receive the `execute_command` tool for running shell commands.

package/.docs/reference/streaming/agents/stream.md

@@ -214,6 +214,10 @@ const stream = await agent.stream('message for agent')
 
 **options.versions.agents.status** (`'draft' | 'published'`): Target the latest version with this publication status.
 
+**options.untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations. The agent will automatically re-invoke the LLM when background tasks complete, streaming continuation turns through the same \`fullStream\`. Pass \`true\` for default settings (5 min idle timeout), or an object with \`maxIdleMs\` to configure. Requires memory. Replaces the standalone \`streamUntilIdle()\` method.
+
+**options.untilIdle.maxIdleMs** (`number`): Closes the outer stream after this many ms of idleness between turns. The timer only runs while the wrapper is between turns. Default: 5 minutes.
+
 ## Returns
 
 **stream** (`MastraModelOutput<Output>`): Returns a MastraModelOutput instance that provides access to the streaming output.

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -2,6 +2,17 @@
 
 **Added in:** `@mastra/core@1.29.0`
 
+> **Deprecated:** `streamUntilIdle()` is deprecated. Use `stream()` with the `untilIdle` option instead:
+>
+> ```ts
+> const result = await agent.stream('Research solana for me', {
+>   untilIdle: true,
+>   memory: { thread: 't1', resource: 'u1' },
+> })
+> ```
+>
+> Pass `untilIdle: { maxIdleMs: 60_000 }` to configure the idle timeout.
+
 `streamUntilIdle()` streams an agent's response and keeps the stream open until every background task dispatched during the run completes. When a task finishes, its result is written to memory and the agentic loop re-enters automatically so the LLM can react to it. The stream closes once no tasks are running and no completions are queued.
 
 Use it when the agent dispatches background tasks (typically long-running tools or subagents) and you want a single stream that spans the initial response **plus** every continuation triggered by a task completion. For foreground-only runs or if you prefer to manage the continuation manually (manually prompt agent to process the result), use [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream).

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

@@ -31,7 +31,11 @@ const workspace = new Workspace({
 
 **filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives \`requestContext\` and returns a filesystem per request. See \[dynamic filesystem]\(/docs/workspace/filesystem#dynamic-filesystem).
 
-**sandbox** (`WorkspaceSandbox`): Sandbox provider instance (e.g., LocalSandbox)
+**sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives \`requestContext\` and returns a sandbox per request. See \[dynamic sandbox]\(/docs/workspace/sandbox#dynamic-sandbox).
+
+**instructions.dynamicSandbox** (`'placeholder' | 'resolve' | (({ requestContext }) => string)`): Controls how a resolver-backed \`sandbox\` contributes to workspace instructions. \`'placeholder'\` (default) emits stable text without calling the resolver. \`'resolve'\` calls the resolver and uses the sandbox's own instructions. A function returns custom text without resolving. Has no effect on a static sandbox. (Default: `'placeholder'`)
+
+**sandboxCacheKey** (`({ requestContext }) => string | undefined`): Stable cache key for a resolver-backed \`sandbox\`. When set, resolved sandboxes are memoized per key instead of per \`RequestContext\` instance, so background-process tools reach the same sandbox across follow-up requests. Has no effect on a static sandbox.
 
 **bm25** (`boolean | BM25Config`): Enable BM25 keyword search. Pass true for defaults or a config object. (Default: `undefined`)
 
@@ -124,7 +128,7 @@ Tool names must be unique across all workspace tools. Setting a custom name that
 
 **filesystem** (`WorkspaceFilesystem | undefined`): The static filesystem provider. Returns \`undefined\` when a resolver function is configured — use \`hasFilesystemConfig()\` to check availability.
 
-**sandbox** (`WorkspaceSandbox | undefined`): The sandbox provider
+**sandbox** (`WorkspaceSandbox | undefined`): The static sandbox provider. Returns \`undefined\` when a resolver function is configured — use \`hasSandboxConfig()\` to check availability.
 
 **skills** (`WorkspaceSkills | undefined`): Skills interface for accessing SKILL.md files
 
@@ -198,6 +202,20 @@ const info = await workspace.getInfo()
 // { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? }
 ```
 
+Pass `resolveDynamicProviders: false` to report resolver-backed providers as dynamic without invoking their resolver.
+
+```typescript
+const info = await workspace.getInfo({ resolveDynamicProviders: false })
+```
+
+**Parameters:**
+
+**options.includeFileCount** (`boolean`): Whether to count total files. This can be slow for large workspaces.
+
+**options.requestContext** (`RequestContext`): Passed to dynamic provider resolvers when \`resolveDynamicProviders\` is enabled.
+
+**options.resolveDynamicProviders** (`boolean`): Whether to invoke dynamic provider resolvers. Set to \`false\` when you only need metadata and want resolver-backed providers reported as \`dynamic\`. (Default: `true`)
+
 #### `getInstructions(opts?)`
 
 Returns combined instructions from the filesystem and sandbox providers. Injected into the agent's system message to help it understand the execution context.
@@ -218,6 +236,20 @@ const instructions = workspace.getInstructions({ requestContext })
 
 **Returns:** `string`
 
+#### `getInstructionsAsync(opts?)`
+
+Returns combined workspace instructions. Use this when the workspace uses resolver-backed providers. A dynamic filesystem is resolved per request; a dynamic sandbox contributes stable placeholder text unless `instructions.dynamicSandbox` is set to `'resolve'`.
+
+```typescript
+const instructions = await workspace.getInstructionsAsync({ requestContext })
+```
+
+**Parameters:**
+
+**opts.requestContext** (`RequestContext`): Passed to the dynamic filesystem resolver, and to the dynamic sandbox resolver when \`instructions.dynamicSandbox\` is \`'resolve'\`.
+
+**Returns:** `Promise<string>`
+
 To override the default output, pass an `instructions` option to [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem) or [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox).
 
 #### `getToolsConfig()`
@@ -282,6 +314,56 @@ const fs = await workspace.resolveFilesystem({ requestContext: ctx })
 
 **Returns:** `Promise<WorkspaceFilesystem | undefined>`
 
+### Dynamic sandbox
+
+#### `hasSandboxConfig()`
+
+Check whether a sandbox is configured, either as a static instance or a resolver function. Use this instead of checking `workspace.sandbox` directly, because a resolver-based workspace returns `undefined` from the `sandbox` property.
+
+```typescript
+if (workspace.hasSandboxConfig()) {
+  // Sandbox tools are available
+}
+```
+
+**Returns:** `boolean`
+
+#### `resolveSandbox({ requestContext })`
+
+Resolve the sandbox for a given request context. When a resolver function is configured, calls it with the provided `requestContext`. When a static sandbox is configured, returns it directly. Returns `undefined` if no sandbox is configured.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const ctx = new RequestContext([['user-id', 'alice']])
+const sandbox = await workspace.resolveSandbox({ requestContext: ctx })
+```
+
+**Parameters:**
+
+**requestContext** (`RequestContext`): The request context to pass to the resolver function.
+
+**Returns:** `Promise<WorkspaceSandbox | undefined>`
+
+#### `clearSandboxCache(cacheKey?)`
+
+Clear resolver-backed sandboxes cached by `sandboxCacheKey`. Pass a cache key to clear one entry, or omit it to clear all keyed sandbox entries.
+
+This method does not clear the per-`RequestContext` weak cache. Those entries are garbage-collection managed.
+
+The workspace does not own resolver-returned sandboxes. This method only drops workspace references. Destroy the sandbox in your own lifecycle code.
+
+```typescript
+workspace.clearSandboxCache('thread-123')
+workspace.clearSandboxCache()
+```
+
+**Parameters:**
+
+**cacheKey** (`string`): The cache key to clear. Omit this value to clear all keyed sandbox entries.
+
+**Returns:** `void`
+
 ## Agent tools
 
 A workspace provides tools to agents based on what's configured.
@@ -333,6 +415,8 @@ Added when a sandbox is configured:
 | `mastra_workspace_get_process_output` | Get stdout, stderr, and status of a background process by PID. Accepts `tail` to limit output lines and `wait: true` to block until exit. Only available when the sandbox has a process manager. |
 | `mastra_workspace_kill_process`       | Kill a background process by PID. Returns the last 50 lines of output. Only available when the sandbox has a process manager.                                                                    |
 
+With a static sandbox, capability checks (`executeCommand`, `processes`) decide which tool variants are exposed. With a [dynamic sandbox](https://mastra.ai/docs/workspace/sandbox), all sandbox tools are registered and the runtime throws a clear error if the resolved sandbox does not implement a requested capability.
+
 The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle callbacks on background processes:
 
 **backgroundProcesses** (`BackgroundProcessesConfig`): Configuration for handling background processes. Only applicable if the sandbox supports background execution.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.45-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`f82cc72`](https://github.com/mastra-ai/mastra/commit/f82cc72edca0ce636fe18abaf2598d89a0c6bcca), [`fcf6027`](https://github.com/mastra-ai/mastra/commit/fcf602747f6771731dda268ff3493b836f9f0ee9)]:
+  - @mastra/core@1.41.0-alpha.0
+
 ## 1.1.44
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.44",
+  "version": "1.1.45-alpha.0",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.40.0",
+    "@mastra/core": "1.41.0-alpha.0",
     "@mastra/mcp": "^1.9.1"
   },
   "devDependencies": {
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
     "@internal/lint": "0.0.102",
-    "@mastra/core": "1.40.0",
-    "@internal/types-builder": "0.0.77"
+    "@internal/types-builder": "0.0.77",
+    "@mastra/core": "1.41.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {