@mastra/mcp-docs-server 1.1.46-alpha.2 → 1.1.46-alpha.4

package/.docs/reference/workspace/railway-sandbox.md

@@ -0,0 +1,230 @@
+# RailwaySandbox
+
+Executes commands in ephemeral, isolated [Railway](https://docs.railway.com/sandboxes) sandboxes. Each sandbox is an isolated Debian Linux VM provisioned on demand through the Railway TypeScript SDK. Supports command execution with streaming output, command timeouts, configurable idle timeout, `ISOLATED`/`PRIVATE` network isolation, custom base images via the Railway template builder, forking a running sandbox, and reattaching to an existing sandbox by ID.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/railway
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/railway
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/railway
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/railway
+```
+
+Set your Railway credentials in one of three ways.
+
+**Shell export**:
+
+```bash
+export RAILWAY_API_TOKEN=your-api-token
+export RAILWAY_ENVIRONMENT_ID=your-environment-id
+```
+
+**.env file**:
+
+```bash
+RAILWAY_API_TOKEN=your-api-token
+RAILWAY_ENVIRONMENT_ID=your-environment-id
+```
+
+**Constructor**:
+
+```typescript
+new RailwaySandbox({
+  token: 'your-api-token',
+  environmentId: 'your-environment-id',
+})
+```
+
+## Usage
+
+Add a `RailwaySandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { RailwaySandbox } from '@mastra/railway'
+
+const workspace = new Workspace({
+  sandbox: new RailwaySandbox({
+    // token + environmentId read from RAILWAY_API_TOKEN / RAILWAY_ENVIRONMENT_ID
+    idleTimeoutMinutes: 30,
+  }),
+})
+
+const agent = new Agent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  instructions: 'You are a coding assistant working in this workspace.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+
+const response = await agent.generate(
+  'Print "Hello, world!" and show the current working directory.',
+)
+
+console.log(response.text)
+```
+
+### Private networking
+
+Join the environment's private network to reach other Railway services (for example `postgres.railway.internal`):
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new RailwaySandbox({
+    networkIsolation: 'PRIVATE',
+    env: { NODE_ENV: 'production' },
+  }),
+})
+```
+
+The default `ISOLATED` mode allows outbound internet access only, with no private network connectivity.
+
+### Custom base image (templates)
+
+Pre-install packages and run setup steps so every sandbox starts ready. Pass a builder callback over the Railway template builder — the template is built once on the first `start()`:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new RailwaySandbox({
+    template: t => t.withPackages('git', 'curl').run('npm i -g pnpm').workdir('/app'),
+  }),
+})
+```
+
+You can also pass a pre-built `SandboxTemplate` to reuse it across sandboxes without rebuilding. Templates are ignored when `sandboxId` is set, since reattaching uses the existing sandbox's filesystem.
+
+### Forking a running sandbox
+
+Clone a running sandbox's filesystem into a new, independent sandbox — a fresh boot, not live processes. The returned `RailwaySandbox` is already started:
+
+```typescript
+const child = await sandbox.fork({ idleTimeoutMinutes: 15 })
+
+const result = await child.executeCommand('cat', ['/app/state.json'])
+console.log(result.stdout)
+```
+
+The forked sandbox inherits the parent's credentials and defaults unless overridden via the `fork()` options.
+
+### Streaming output
+
+Stream command output in real time via `onStdout` and `onStderr` callbacks:
+
+```typescript
+await sandbox.executeCommand('bash', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
+  onStdout: chunk => process.stdout.write(chunk),
+  onStderr: chunk => process.stderr.write(chunk),
+})
+```
+
+Both callbacks are optional and can be used independently.
+
+### Reattaching to an existing sandbox
+
+A Railway sandbox outlives the process that created it. Reconnect by its Railway ID instead of provisioning a new one:
+
+```typescript
+const sandbox = new RailwaySandbox({ sandboxId: 'existing-railway-sandbox-id' })
+await sandbox._start()
+
+const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+
+**token** (`string`): Railway API token for authentication. Falls back to the RAILWAY\_API\_TOKEN environment variable.
+
+**environmentId** (`string`): Railway environment ID. Falls back to the RAILWAY\_ENVIRONMENT\_ID environment variable.
+
+**sandboxId** (`string`): Reattach to an existing Railway sandbox by its Railway ID instead of creating a new one. When set, start() calls Sandbox.connect().
+
+**idleTimeoutMinutes** (`number`): How long the sandbox can sit idle (no exec interaction) before Railway destroys it automatically. The valid range and default depend on your Railway plan.
+
+**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): Network access mode. 'ISOLATED' allows outbound internet only; 'PRIVATE' joins the environment's private network. (Default: `'ISOLATED'`)
+
+**env** (`Record<string, string>`): Environment variables baked into the sandbox, available to every command. (Default: `{}`)
+
+**template** (`SandboxTemplate | (base: SandboxTemplate) => SandboxTemplate`): Provision the sandbox from a custom base image built with the Railway template builder. Accepts a builder callback or a pre-built template. Ignored when sandboxId is set.
+
+**timeout** (`number`): Default execution timeout in milliseconds applied to commands that do not specify their own timeout. Commands run until they exit when omitted.
+
+**instructions** (`string | (opts) => string`): Override the default agent instructions. A string replaces them entirely; a function receives the default instructions and returns the final text.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('RailwaySandbox').
+
+**provider** (`string`): Provider identifier ('railway').
+
+**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'stopped' | 'destroyed' | 'error'
+
+**railway** (`Sandbox`): The underlying Railway Sandbox instance for direct SDK access. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`RailwayProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Methods
+
+**fork** (`(options?) => Promise<RailwaySandbox>`): Clone this running sandbox into a new, independent RailwaySandbox. The returned sandbox is already started and reattached to the forked Railway sandbox. Accepts optional id, idleTimeoutMinutes, networkIsolation, and env overrides. Throws SandboxNotReadyError if this sandbox has not been started.
+
+## Background processes
+
+`RailwaySandbox` includes a built-in process manager for spawning and managing background processes. Each spawned process runs as a Railway `exec` session.
+
+```typescript
+const sandbox = new RailwaySandbox()
+await sandbox.start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// Interact with the process
+console.log(handle.stdout)
+await handle.kill()
+```
+
+Railway's `exec` API does not stream stdin, so `sendStdin()` is not supported.
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Editor provider
+
+Register the provider with `MastraEditor` to hydrate stored sandbox configs into runtime instances:
+
+```typescript
+import { railwaySandboxProvider } from '@mastra/railway'
+
+const editor = new MastraEditor({
+  sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
+})
+```
+
+See the [Sandbox provider reference](https://mastra.ai/reference/editor/sandbox-provider) for details on registering custom sandbox providers.

package/.docs/reference/workspace/vercel-microvm-sandbox.md

@@ -187,7 +187,7 @@ await handle.kill()
 
 See the [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
 
-> **Note:** The Vercel Sandbox SDK does not expose a stdin channel for running commands, so `handle.sendStdin()` throws. Filesystem mounting (FUSE) is also not supported by this provider.
+> **Note:** The Vercel Sandbox SDK doesn't expose a stdin channel for running commands, so `handle.sendStdin()` throws. Filesystem mounting (FUSE) is also not supported by this provider.
 
 ## Limits
 

package/.docs/reference/workspace/vercel.md

@@ -4,7 +4,7 @@ Executes commands as [Vercel](https://vercel.com) serverless functions. Provides
 
 > **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
-> **Warning:** VercelSandbox is stateless. There is no persistent filesystem, no interactive shell, and no support for long-running or background processes. Only `/tmp` is writable and is ephemeral between invocations.
+> **Warning:** VercelSandbox is stateless. No persistent filesystem, no interactive shell, and no support for long-running or background processes exist. Only `/tmp` is writable and is ephemeral between invocations.
 
 > **Note:** For a full Linux MicroVM with a persistent filesystem, `sudo` access, exposed ports, and background processes, use [`VercelMicroVMSandbox`](https://mastra.ai/reference/workspace/vercel-microvm-sandbox), which is backed by the [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) product.
 
@@ -110,7 +110,7 @@ VercelSandbox uses serverless functions under the hood, which means:
 - **No persistent filesystem**: Files written to `/tmp` are ephemeral and cleared between invocations.
 - **No interactive shell**: Commands run via `/bin/sh -c` with no stdin streaming.
 - **No background processes**: No process manager, PIDs, or long-running tasks.
-- **No mounting**: Cloud storage mounting (S3, GCS) is not supported.
+- **No mounting**: Cloud storage mounting (S3, GCS) isn't supported.
 - **Timeout limits**: Maximum execution time is bounded by `maxDuration` (default 60s).
 
 ## Related

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

@@ -65,6 +65,8 @@ const workspace = new Workspace({
 
 **tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken.
 
+**tools.hooks** (`WorkspaceToolHooks`): Hooks that run before and after every enabled workspace tool call. See Tool hooks below.
+
 **operationTimeout** (`number`): Timeout for operations in milliseconds
 
 ## Tool configuration
@@ -118,6 +120,34 @@ const workspace = new Workspace({
 
 Tool names must be unique across all workspace tools. Setting a custom name that conflicts with another tool's default or custom name throws an error.
 
+### Tool hooks
+
+Set `tools.hooks` to run logic before and after every enabled workspace tool call. Hooks run after name remapping, so the context includes both the exposed `toolName` and the original `workspaceToolName`.
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  id: 'my-workspace',
+  tools: {
+    hooks: {
+      beforeToolCall: ({ toolName, workspaceToolName, input }) => {
+        console.log(`Running ${toolName} (${workspaceToolName})`, input)
+      },
+      afterToolCall: ({ toolName, output, error }) => {
+        console.log(`Finished ${toolName}`, { output, error })
+      },
+    },
+  },
+})
+```
+
+**beforeToolCall** (`(context: WorkspaceToolHookContext) => void | WorkspaceToolBeforeHookResult | Promise<void | WorkspaceToolBeforeHookResult>`): Runs before a workspace tool executes. Receives \`{ toolName, workspaceToolName, input, context }\`. Return \`{ proceed: false, output }\` to skip the tool call and use \`output\` as its result.
+
+**afterToolCall** (`(context: WorkspaceToolAfterHookContext) => void | Promise<void>`): Runs after a workspace tool executes. Receives \`{ toolName, workspaceToolName, input, context, output, error }\`. \`output\` is undefined when the tool throws, and \`error\` is set instead.
+
+If the owning agent also defines [tool hooks](https://mastra.ai/reference/agents/agent), workspace hooks run inside the agent hook wrapper: agent `beforeToolCall` runs first, then workspace `beforeToolCall`, then the tool, then workspace `afterToolCall`, then agent `afterToolCall`.
+
 ## Properties
 
 **id** (`string`): Workspace identifier
@@ -170,6 +200,12 @@ Destroy the workspace and clean up resources.
 await workspace.destroy()
 ```
 
+`destroy()` closes workspace-owned resources in order: language servers, browsers, sandbox providers, and filesystem providers. It also clears cached sandbox references.
+
+Call `destroy()` when your application is done with a workspace. `mastra.shutdown()` calls it for registered workspaces during shutdown. To remove a workspace from the Mastra registry, use [`mastra.removeWorkspace()`](https://mastra.ai/reference/core/removeWorkspace).
+
+`LocalFilesystem.destroy()` doesn't delete files on disk. Resolver-backed filesystem and sandbox providers are owned by your application and must be cleaned up by your application.
+
 ### Search operations
 
 #### `index(path, content, options?)`
@@ -349,9 +385,9 @@ const sandbox = await workspace.resolveSandbox({ requestContext: ctx })
 
 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.
+This method doesn't 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.
+The workspace doesn't own resolver-returned sandboxes. This method only drops workspace references. Destroy the sandbox in your own lifecycle code.
 
 ```typescript
 workspace.clearSandboxCache('thread-123')
@@ -415,7 +451,7 @@ 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.
+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 doesn't implement a requested capability.
 
 The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle callbacks on background processes:
 

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/mcp-docs-server
 
+## 1.1.46-alpha.4
+
+### Patch Changes
+
+- Fixed the MCP docs server package root export so importing @mastra/mcp-docs-server loads a published runtime file. Fixes #17700. ([#17709](https://github.com/mastra-ai/mastra/pull/17709))
+
+- Updated dependencies [[`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`306909a`](https://github.com/mastra-ai/mastra/commit/306909a693de77d709b38706e2673c9547d24a28), [`5191af8`](https://github.com/mastra-ai/mastra/commit/5191af80c799eea25357c545fc05d91b3883531d), [`43bd3d4`](https://github.com/mastra-ai/mastra/commit/43bd3d421987463fdf35386a45199c49499ed069), [`e6fa79e`](https://github.com/mastra-ai/mastra/commit/e6fa79ec72a2ddffdd25e85270398951e9d552a4), [`904bcdf`](https://github.com/mastra-ai/mastra/commit/904bcdf7b8004aa7be823f9f70ca63580e47e470), [`7f5ee1d`](https://github.com/mastra-ai/mastra/commit/7f5ee1dca46daee8d2817f2ebe49e6335da81956), [`1e9aab5`](https://github.com/mastra-ai/mastra/commit/1e9aab50ff11e6e88fde4d7cbf512c44a9fe8d61), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`2656d9c`](https://github.com/mastra-ai/mastra/commit/2656d9c2976d4f3354253bfbbbf9b88a1b2bbf34), [`63e3fe1`](https://github.com/mastra-ai/mastra/commit/63e3fe13cc1ea96f91d7c68aea92f400faf9e4da), [`1d4ce8d`](https://github.com/mastra-ai/mastra/commit/1d4ce8daaa54511f325c1b609d31b8e54009d677), [`8c68372`](https://github.com/mastra-ai/mastra/commit/8c68372e85fe0b066ec12c58bd29ffb93e54c552)]:
+  - @mastra/core@1.42.0-alpha.4
+  - @mastra/mcp@1.10.0-alpha.1
+
+## 1.1.46-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`053735a`](https://github.com/mastra-ai/mastra/commit/053735a75c2c18e23ce34d9468007efa4a45f4c4), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`a952852`](https://github.com/mastra-ai/mastra/commit/a952852c971a21fb646cd907c75fcf4443cdc963)]:
+  - @mastra/core@1.42.0-alpha.3
+
 ## 1.1.46-alpha.2
 
 ### Patch Changes