@mastra/mcp-docs-server 1.1.8 → 1.1.9-alpha.1

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

@@ -54,7 +54,7 @@ const response = await agent.generate('Run npm install')
 
 **nativeSandbox** (`NativeSandboxConfig`): Configuration for native sandboxing (see NativeSandboxConfig below).
 
-## NativeSandboxConfig
+## `NativeSandboxConfig`
 
 Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'` or `'bwrap'`).
 
@@ -82,104 +82,7 @@ Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'
 
 **workingDirectory** (`string`): The configured working directory
 
-## Methods
-
-### `start()`
-
-Initialize and start the sandbox. Creates the working directory and sets up seatbelt profiles if using native isolation.
-
-```typescript
-await sandbox.start()
-```
-
-Called automatically by `workspace.init()` or on first `executeCommand()` call.
-
-### `stop()`
-
-Stop the sandbox.
-
-```typescript
-await sandbox.stop()
-```
-
-### `destroy()`
-
-Clean up sandbox resources. Removes seatbelt profiles if they were auto-generated.
-
-```typescript
-await sandbox.destroy()
-```
-
-Called by `workspace.destroy()`.
-
-### `isReady()`
-
-Check if the sandbox is ready for operations.
-
-```typescript
-const ready = await sandbox.isReady()
-// true if status is 'running'
-```
-
-### `executeCommand(command, args?, options?)`
-
-Execute a shell command in the sandbox.
-
-```typescript
-const listResult = await sandbox.executeCommand('ls', ['-la'])
-const installResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
-  timeout: 60000,
-  env: { NODE_ENV: 'development' },
-})
-```
-
-**Parameters:**
-
-**command** (`string`): Command to execute
-
-**args** (`string[]`): Command arguments
-
-**options.timeout** (`number`): Execution timeout in milliseconds
-
-**options.cwd** (`string`): Working directory for the command
-
-**options.env** (`Record<string, string>`): Additional environment variables
-
-**options.onStdout** (`(data: string) => void`): Callback for stdout streaming
-
-**options.onStderr** (`(data: string) => void`): Callback for stderr streaming
-
-### `getInfo()`
-
-Get sandbox status and resource information.
-
-```typescript
-const info = await sandbox.getInfo()
-// { status: 'running', resources: { ... } }
-```
-
-### `getInstructions(opts?)`
-
-Returns a description of how this sandbox works. When assigned to an agent, this is injected into the agent's system message.
-
-```typescript
-const instructions = sandbox.getInstructions()
-// 'Local command execution. Working directory: "/workspace".'
-```
-
-Pass `requestContext` to enable per-request customization when the `instructions` constructor option is a function:
-
-```typescript
-const instructions = sandbox.getInstructions({ requestContext })
-```
-
-**Parameters:**
-
-**opts.requestContext** (`RequestContext`): Forwarded to the \`instructions\` function if one was provided in the constructor.
-
-**Returns:** `string`
-
-To override the default output, pass an `instructions` option to the constructor. See [constructor parameters](#constructor-parameters).
+**processes** (`LocalProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
 
 ## Path Resolution
 
@@ -209,7 +112,28 @@ const sandbox = new LocalSandbox({
 
 Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my-project/workspace`. This ensures commands run from a consistent directory regardless of how you run your code.
 
-## Static Methods
+## Background processes
+
+`LocalSandbox` includes a built-in process manager for spawning and managing background processes. Processes run as child processes on the local machine using `child_process.spawn`.
+
+```typescript
+const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
+await sandbox.start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js')
+
+// Read output, send stdin, kill
+console.log(handle.stdout)
+await handle.sendStdin('input\n')
+await handle.kill()
+```
+
+When native isolation is enabled (`seatbelt` or `bwrap`), spawned processes are also wrapped with the same isolation backend.
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Static methods
 
 ### `detectIsolation()`
 
@@ -220,7 +144,7 @@ const detection = LocalSandbox.detectIsolation()
 // { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
 ```
 
-## Environment Isolation
+## Environment isolation
 
 By default, `LocalSandbox` only includes `PATH` in the environment. This allows commands to run while preventing accidental exposure of API keys and secrets.
 
@@ -246,7 +170,7 @@ const devSandbox = new LocalSandbox({
 })
 ```
 
-## Native OS Sandboxing
+## Native OS sandboxing
 
 `LocalSandbox` supports native OS-level sandboxing for additional security:
 
@@ -296,6 +220,7 @@ This separation prevents sandboxed processes from reading or modifying their own
 
 ## Related
 
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
 - [Workspace Overview](https://mastra.ai/docs/workspace/overview)

package/.docs/reference/workspace/process-manager.md

@@ -0,0 +1,296 @@
+# SandboxProcessManager
+
+**Added in:** `@mastra/core@1.7.0`
+
+Abstract base class for managing background processes in sandboxes. Provides methods to spawn processes, list them, get handles by PID, and kill them.
+
+[`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox), [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox), [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) all include built-in process managers. You don't need to instantiate this class directly unless you're building a custom sandbox provider.
+
+## Usage example
+
+Access the process manager through the sandbox's `processes` property:
+
+```typescript
+import { LocalSandbox } from '@mastra/core/workspace'
+
+const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
+await sandbox.start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// List all tracked processes
+const procs = await sandbox.processes.list()
+
+// Get a handle by PID
+const proc = await sandbox.processes.get(handle.pid)
+
+// Kill a process
+await sandbox.processes.kill(handle.pid)
+```
+
+## Methods
+
+### `spawn(command, options?)`
+
+Spawn a background process. Returns a `ProcessHandle` immediately without waiting for the process to finish.
+
+```typescript
+const handle = await sandbox.processes.spawn('npm run dev', {
+  cwd: '/app',
+  env: { NODE_ENV: 'development' },
+  onStdout: data => console.log(data),
+})
+```
+
+**Parameters:**
+
+**command** (`string`): The command to run. Interpreted by the shell.
+
+**options** (`SpawnProcessOptions`): Optional settings for the spawned process.
+
+**options.timeout** (`number`): Timeout in milliseconds. Kills the process if exceeded.
+
+**options.env** (`NodeJS.ProcessEnv`): Environment variables for the process.
+
+**options.cwd** (`string`): Working directory for the process.
+
+**options.onStdout** (`(data: string) => void`): Callback for stdout chunks. Called as data arrives.
+
+**options.onStderr** (`(data: string) => void`): Callback for stderr chunks. Called as data arrives.
+
+**options.abortSignal** (`AbortSignal`): Signal to abort the process. When aborted, the process is killed.
+
+**Returns:** `Promise<ProcessHandle>`
+
+### `list()`
+
+List all tracked processes. Returns info about each process including PID, running state, and exit code.
+
+```typescript
+const procs = await sandbox.processes.list()
+for (const proc of procs) {
+  console.log(proc.pid, proc.running, proc.exitCode)
+}
+```
+
+**Returns:** `Promise<ProcessInfo[]>`
+
+### `get(pid)`
+
+Get a handle to a process by PID. Returns `undefined` if the process isn't found or has already been dismissed.
+
+```typescript
+const handle = await sandbox.processes.get(1234)
+if (handle) {
+  console.log(handle.stdout)
+  await handle.kill()
+}
+```
+
+**Returns:** `Promise<ProcessHandle | undefined>`
+
+### `kill(pid)`
+
+Kill a process by PID. Waits for the process to terminate before returning. Returns `true` if the process was killed, `false` if it wasn't found.
+
+```typescript
+const killed = await sandbox.processes.kill(handle.pid)
+```
+
+**Returns:** `Promise<boolean>`
+
+## `ProcessInfo`
+
+Information about a tracked process, returned by `list()`.
+
+**pid** (`number`): Process ID.
+
+**command** (`string`): The command that was executed.
+
+**running** (`boolean`): Whether the process is still running.
+
+**exitCode** (`number`): Exit code if the process has finished.
+
+***
+
+## `ProcessHandle`
+
+Handle to a spawned background process. Provides methods to read output, send stdin, wait for completion, and kill the process.
+
+You don't create `ProcessHandle` instances directly — they're returned by `spawn()` and `get()`.
+
+### Usage example
+
+```typescript
+const handle = await sandbox.processes.spawn('npm run dev', {
+  onStdout: data => console.log(data),
+})
+
+// Read accumulated output
+console.log(handle.pid)
+console.log(handle.stdout)
+console.log(handle.stderr)
+console.log(handle.exitCode) // undefined while running
+
+// Wait for completion
+const result = await handle.wait()
+
+// Send stdin
+await handle.sendStdin('input data\n')
+
+// Kill the process
+await handle.kill()
+```
+
+### Properties
+
+**pid** (`number`): Process ID.
+
+**stdout** (`string`): Accumulated stdout output so far.
+
+**stderr** (`string`): Accumulated stderr output so far.
+
+**exitCode** (`number | undefined`): Exit code. undefined while the process is still running.
+
+**command** (`string | undefined`): The command that was spawned. Set automatically by the process manager.
+
+**reader** (`Readable`): Readable stream of stdout. Useful for protocols like LSP or JSON-RPC that communicate over stdio.
+
+**writer** (`Writable`): Writable stream to stdin. Useful for protocols like LSP or JSON-RPC that communicate over stdio.
+
+### Methods
+
+#### `wait(options?)`
+
+Wait for the process to exit and return the result. Optionally pass `onStdout`/`onStderr` callbacks to stream output while waiting. Callbacks are automatically removed when `wait()` resolves.
+
+```typescript
+// Simple wait
+const result = await handle.wait()
+console.log(result.success, result.exitCode, result.stdout)
+
+// Wait with streaming
+const result = await handle.wait({
+  onStdout: data => process.stdout.write(data),
+  onStderr: data => process.stderr.write(data),
+})
+```
+
+**Parameters:**
+
+**options** (`WaitOptions`): Optional settings for waiting.
+
+**options.onStdout** (`(data: string) => void`): Callback for stdout chunks while waiting.
+
+**options.onStderr** (`(data: string) => void`): Callback for stderr chunks while waiting.
+
+**Returns:** `Promise<CommandResult>`
+
+The `CommandResult` object contains:
+
+**success** (`boolean`): true if exit code is 0.
+
+**exitCode** (`number`): Numeric exit code.
+
+**stdout** (`string`): Full stdout output.
+
+**stderr** (`string`): Full stderr output.
+
+**executionTimeMs** (`number`): Execution time in milliseconds.
+
+**timedOut** (`boolean`): true if the process was killed due to timeout.
+
+**killed** (`boolean`): true if the process was killed by a signal.
+
+#### `kill()`
+
+Kill the process. Returns `true` if the process was killed, `false` if it had already exited.
+
+```typescript
+const killed = await handle.kill()
+```
+
+**Returns:** `Promise<boolean>`
+
+#### `sendStdin(data)`
+
+Send data to the process's stdin. Throws if the process has already exited or stdin isn't available.
+
+```typescript
+await handle.sendStdin('console.log("hello")\n')
+```
+
+**Returns:** `Promise<void>`
+
+## Stream interop
+
+`ProcessHandle` exposes `reader` and `writer` properties for integration with Node.js stream-based protocols like LSP or JSON-RPC:
+
+```typescript
+import {
+  createMessageConnection,
+  StreamMessageReader,
+  StreamMessageWriter,
+} from 'vscode-jsonrpc/node'
+
+const handle = await sandbox.processes.spawn('typescript-language-server --stdio')
+
+const connection = createMessageConnection(
+  new StreamMessageReader(handle.reader),
+  new StreamMessageWriter(handle.writer),
+)
+connection.listen()
+```
+
+## Building a custom process manager
+
+To build a process manager for a custom sandbox provider, extend `SandboxProcessManager` and implement `spawn()` and `list()`. The base class automatically wraps your methods with `ensureRunning()` so the sandbox starts before any process operation.
+
+```typescript
+import { SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace'
+import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace'
+
+class MyProcessManager extends SandboxProcessManager<MySandbox> {
+  async spawn(command: string, options: SpawnProcessOptions = {}): Promise<ProcessHandle> {
+    // Your spawn implementation
+    const handle = new MyProcessHandle(/* ... */)
+    this._tracked.set(handle.pid, handle)
+    return handle
+  }
+
+  async list(): Promise<ProcessInfo[]> {
+    return Array.from(this._tracked.values()).map(handle => ({
+      pid: handle.pid,
+      running: handle.exitCode === undefined,
+      exitCode: handle.exitCode,
+    }))
+  }
+}
+```
+
+Pass the process manager to your sandbox via the `processes` option in `MastraSandbox`:
+
+```typescript
+class MySandbox extends MastraSandbox {
+  constructor() {
+    super({
+      name: 'MySandbox',
+      processes: new MyProcessManager(),
+    })
+  }
+}
+```
+
+When a process manager is provided, `MastraSandbox` automatically creates a default `executeCommand` implementation that uses `spawn()` + `wait()`, so you don't need to implement both.
+
+## Related
+
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [DaytonaSandbox reference](https://mastra.ai/reference/workspace/daytona-sandbox)

package/.docs/reference/workspace/s3-filesystem.md

@@ -6,10 +6,30 @@ Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2,
 
 ## Installation
 
+**npm**:
+
 ```bash
 npm install @mastra/s3
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/s3
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/s3
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/s3
+```
+
 ## Usage
 
 Add an `S3Filesystem` to a workspace and assign it to an agent:
@@ -145,7 +165,7 @@ const config = filesystem.getMountConfig()
 // { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
 ```
 
-## Mounting in E2B Sandboxes
+## Mounting in E2B sandboxes
 
 S3Filesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
 

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

@@ -2,7 +2,11 @@
 
 **Added in:** `@mastra/core@1.1.0`
 
-The `WorkspaceSandbox` interface defines how workspaces execute commands.
+The `WorkspaceSandbox` interface defines how workspaces execute commands and manage background processes.
+
+## Properties
+
+**processes** (`SandboxProcessManager`): Background process manager. If not implemented, process management tools won't be available. See SandboxProcessManager reference.
 
 ## Methods
 
@@ -47,6 +51,8 @@ const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
 
 **args** (`string[]`): Command arguments
 
+**options** (`Options`): Configuration options.
+
 **options.timeout** (`number`): Execution timeout in milliseconds
 
 **options.cwd** (`string`): Working directory for the command
@@ -83,5 +89,7 @@ const instructions = sandbox.getInstructions?.()
 
 ## Related
 
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
 - [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem)