@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

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

@@ -0,0 +1,289 @@
+# E2BSandbox
+
+Executes commands in isolated [E2B](https://e2b.dev) cloud sandboxes. Provides secure, ephemeral environments with support for mounting cloud storage.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+```bash
+npm install @mastra/e2b
+```
+
+## Usage
+
+Add an `E2BSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    timeout: 60_000, // 60 second timeout (default: 5 minutes)
+  }),
+})
+
+const agent = new Agent({
+  name: 'dev-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+})
+```
+
+## Constructor parameters
+
+**apiKey?:** (`string`): E2B API key. Falls back to E2B\_API\_KEY environment variable.
+
+**timeout?:** (`number`): Execution timeout in milliseconds (Default: `300000 (5 minutes)`)
+
+**template?:** (`string | TemplateBuilder | function`): Sandbox template specification. Can be a template ID string, a TemplateBuilder, or a function that customizes the default template.
+
+**env?:** (`Record<string, string>`): Environment variables to set in the sandbox
+
+**id?:** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
+
+**domain?:** (`string`): Domain for self-hosted E2B. Falls back to E2B\_DOMAIN env var.
+
+**apiUrl?:** (`string`): API URL for self-hosted E2B. Falls back to E2B\_API\_URL env var.
+
+**accessToken?:** (`string`): Access token for authentication. Falls back to E2B\_ACCESS\_TOKEN env var.
+
+## Properties
+
+**id:** (`string`): Sandbox instance identifier
+
+**name:** (`string`): Provider name ('E2BSandbox')
+
+**provider:** (`string`): Provider identifier ('e2b')
+
+**status:** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'error'
+
+**supportsMounting:** (`boolean`): Always true - E2B sandboxes support mounting cloud filesystems
+
+## Methods
+
+### `start()`
+
+Initialize and start the sandbox. Creates the E2B sandbox instance and mounts any configured filesystems.
+
+```typescript
+await sandbox.start()
+```
+
+Called automatically on first command execution or by `workspace.init()`.
+
+### `stop()`
+
+Stop the sandbox and release resources.
+
+```typescript
+await sandbox.stop()
+```
+
+### `destroy()`
+
+Clean up sandbox resources completely.
+
+```typescript
+await sandbox.destroy()
+```
+
+### `executeCommand(command, args?, options?)`
+
+Execute a shell command in the sandbox.
+
+```typescript
+const result = await sandbox.executeCommand('ls', ['-la'])
+const npmResult = await sandbox.executeCommand('npm', ['install', 'lodash'], {
+  timeout: 60000,
+  cwd: '/app',
+})
+```
+
+**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
+
+### `canMount(filesystem)`
+
+Check if a filesystem can be mounted into this sandbox.
+
+```typescript
+const canMount = sandbox.canMount(s3Filesystem)
+// true for S3Filesystem and GCSFilesystem
+```
+
+### `mount(filesystem, mountPath)`
+
+Mount a filesystem into the sandbox at the specified path.
+
+```typescript
+await sandbox.mount(s3Filesystem, '/mnt/data')
+```
+
+### `unmount(mountPath)`
+
+Unmount a previously mounted filesystem.
+
+```typescript
+await sandbox.unmount('/mnt/data')
+```
+
+### `getInfo()`
+
+Get sandbox status and resource information.
+
+```typescript
+const info = await sandbox.getInfo()
+// { id: '...', name: 'E2BSandbox', provider: 'e2b', status: 'ready', supportsMounting: true }
+```
+
+## Mounting Cloud Storage
+
+E2B sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as local directories inside the sandbox. This is useful for:
+
+- Processing large datasets stored in cloud buckets
+- Writing output files directly to cloud storage
+- Sharing data between sandbox sessions
+
+### Using the mounts config
+
+The simplest way to mount filesystems is through the workspace `mounts` config:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+import { GCSFilesystem } from '@mastra/gcs'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  mounts: {
+    '/s3-data': new S3Filesystem({
+      bucket: 'my-s3-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+    '/gcs-data': new GCSFilesystem({
+      bucket: 'my-gcs-bucket',
+      projectId: 'my-project',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+When the sandbox starts, the filesystems are automatically mounted at the specified paths. Code running in the sandbox can then access files at `/s3-data` and `/gcs-data` as if they were local directories.
+
+### How mounting works
+
+E2B sandboxes use FUSE (Filesystem in Userspace) to mount cloud storage:
+
+- **S3/R2**: Mounted via [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse)
+- **GCS**: Mounted via [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse)
+
+The E2B sandbox automatically installs the required FUSE tools when mounting is used. For best performance, pre-build a custom template with the tools installed.
+
+## Custom Templates
+
+By default, when no template is specified, E2BSandbox automatically builds a template with `s3fs` installed for S3 mounting support. This template is cached and reused across sandbox instances.
+
+For GCS mounting, `gcsfuse` is automatically installed at mount time if not already present. For additional tools or faster cold starts, use custom templates.
+
+### Using an existing template
+
+If you have a pre-built template, pass its ID:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    template: 'my-custom-template',
+  }),
+})
+```
+
+### Customizing the default template
+
+Pass a function to customize the default mountable template. The function receives a `TemplateBuilder` and should return the modified template:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    template: base =>
+      base
+        .aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
+        .pipInstall(['pandas', 'numpy'])
+        .npmInstall(['sharp']),
+  }),
+})
+```
+
+The template builder supports method chaining with operations like:
+
+- `aptInstall(packages)` - Install system packages
+- `pipInstall(packages)` - Install Python packages
+- `npmInstall(packages)` - Install Node.js packages
+- `runCmd(command)` - Run shell commands
+- `setEnvs(vars)` - Set environment variables
+- `copy(src, dest)` - Copy files into the template
+
+See [E2B's template documentation](https://e2b.dev/docs/template/defining-template) for the full list of available methods.
+
+### Pre-building templates
+
+The default template is built on first use and cached. For faster cold starts or to include GCS support, you can pre-build a template:
+
+```typescript
+import { createDefaultMountableTemplate } from '@mastra/e2b'
+import { Template } from 'e2b'
+
+// Get the default mountable template (includes s3fs)
+const { template, id } = createDefaultMountableTemplate()
+
+// Build and save to E2B
+const result = await Template.build(template, id)
+console.log('Template ID:', result.templateId)
+
+// Use this ID in your E2BSandbox config for instant startup
+const sandbox = new E2BSandbox({
+  template: result.templateId,
+})
+```
+
+For faster GCS cold starts, pre-install `gcsfuse` in a custom template:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({
+    id: 'dev-sandbox',
+    template: base => base.aptInstall(['gcsfuse']),
+  }),
+})
+```
+
+This is optional—`gcsfuse` is installed automatically at mount time if not present.
+
+## Related
+
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -0,0 +1,255 @@
+# WorkspaceFilesystem
+
+**Added in:** `@mastra/core@1.1.0`
+
+The `WorkspaceFilesystem` interface defines how workspaces interact with file storage.
+
+## Methods
+
+### `readFile(path, options?)`
+
+Read file contents.
+
+```typescript
+const content = await filesystem.readFile('/docs/guide.md')
+const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
+```
+
+**Parameters:**
+
+**path:** (`string`): File path relative to basePath
+
+**options.encoding?:** (`'utf-8' | 'binary'`): Text or binary encoding (Default: `'utf-8'`)
+
+**Returns:** `Promise<string | Buffer>`
+
+### `writeFile(path, content, options?)`
+
+Write file contents.
+
+```typescript
+await filesystem.writeFile('/docs/new.md', '# New Document')
+await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): File path relative to basePath
+
+**content:** (`string | Buffer`): File content
+
+**options.recursive?:** (`boolean`): Create parent directories if they don't exist (Default: `false`)
+
+**options.overwrite?:** (`boolean`): Overwrite existing file (Default: `true`)
+
+### `deleteFile(path, options?)`
+
+Delete a file.
+
+```typescript
+await filesystem.deleteFile('/docs/old.md')
+await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
+```
+
+**Parameters:**
+
+**path:** (`string`): File path
+
+**options.force?:** (`boolean`): Don't throw error if file doesn't exist (Default: `false`)
+
+### `appendFile(path, content)`
+
+Append content to a file, creating it if it does not already exist. Parent directories are created automatically.
+
+```typescript
+await filesystem.appendFile('/logs/app.log', 'New log entry\n')
+```
+
+**Parameters:**
+
+**path:** (`string`): File path
+
+**content:** (`string | Buffer`): Content to append
+
+### `copyFile(src, dest, options?)`
+
+Copy a file to a new location.
+
+```typescript
+await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
+```
+
+**Parameters:**
+
+**src:** (`string`): Source file path
+
+**dest:** (`string`): Destination file path
+
+**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
+
+### `moveFile(src, dest, options?)`
+
+Move or rename a file.
+
+```typescript
+await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
+```
+
+**Parameters:**
+
+**src:** (`string`): Source file path
+
+**dest:** (`string`): Destination file path
+
+**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
+
+### `readdir(path, options?)`
+
+List directory contents.
+
+```typescript
+const entries = await filesystem.readdir('/docs')
+// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
+```
+
+**Returns:** `Promise<FileEntry[]>`
+
+```typescript
+interface FileEntry {
+  name: string
+  type: 'file' | 'directory'
+  size?: number
+  isSymlink?: boolean
+  symlinkTarget?: string
+}
+```
+
+### `mkdir(path, options?)`
+
+Create a directory.
+
+```typescript
+await filesystem.mkdir('/docs/api')
+await filesystem.mkdir('/deeply/nested/path', { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): Directory path
+
+**options.recursive?:** (`boolean`): Create parent directories (Default: `false`)
+
+### `rmdir(path, options?)`
+
+Remove a directory.
+
+```typescript
+await filesystem.rmdir('/docs/old')
+await filesystem.rmdir('/docs/nested', { recursive: true })
+```
+
+**Parameters:**
+
+**path:** (`string`): Directory path
+
+**options.recursive?:** (`boolean`): Remove contents recursively (Default: `false`)
+
+**options.force?:** (`boolean`): Don't throw if directory doesn't exist (Default: `false`)
+
+### `exists(path)`
+
+Check if a path exists.
+
+```typescript
+const exists = await filesystem.exists('/docs/guide.md')
+```
+
+**Returns:** `Promise<boolean>`
+
+### `stat(path)`
+
+Get file or directory metadata.
+
+```typescript
+const stat = await filesystem.stat('/docs/guide.md')
+// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }
+```
+
+**Returns:** `Promise<FileStat>`
+
+```typescript
+interface FileStat {
+  name: string // File or directory name (basename only)
+  path: string // Path relative to the filesystem basePath
+  type: 'file' | 'directory'
+  size: number
+  createdAt: Date
+  modifiedAt: Date
+  mimeType?: string
+}
+```
+
+## Optional Methods
+
+### `init()`
+
+Initialize the filesystem. Called by `workspace.init()`.
+
+```typescript
+await filesystem.init?.()
+```
+
+### `destroy()`
+
+Clean up resources. Called by `workspace.destroy()`.
+
+```typescript
+await filesystem.destroy?.()
+```
+
+### `getInfo()`
+
+Get filesystem metadata.
+
+```typescript
+const info = await filesystem.getInfo?.()
+// { id, name, provider, basePath, readOnly, status, storage? }
+```
+
+**Returns:** `Promise<FilesystemInfo>`
+
+```typescript
+interface FilesystemInfo {
+  id: string
+  name: string
+  provider: string
+  basePath?: string
+  readOnly?: boolean
+  status?: string
+  storage?: {
+    totalBytes?: number
+    usedBytes?: number
+    availableBytes?: number
+  }
+}
+```
+
+### `getInstructions(opts?)`
+
+Returns a description of how this filesystem works. Injected into the agent's system message when the workspace is assigned to an agent.
+
+```typescript
+const instructions = filesystem.getInstructions?.()
+// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
+```
+
+**Parameters:**
+
+**opts.requestContext?:** (`RequestContext`): Forwarded to the \`instructions\` function if one was provided in the constructor.
+
+**Returns:** `string`
+
+## Related
+
+- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
+- [Sandbox Interface](https://mastra.ai/reference/workspace/sandbox)

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

@@ -0,0 +1,174 @@
+# GCSFilesystem
+
+Stores files in Google Cloud Storage.
+
+> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+```bash
+npm install @mastra/gcs
+```
+
+## Usage
+
+Add a `GCSFilesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { GCSFilesystem } from '@mastra/gcs'
+
+const workspace = new Workspace({
+  filesystem: new GCSFilesystem({
+    bucket: 'my-gcs-bucket',
+    projectId: 'my-project-id',
+    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+  }),
+})
+
+const agent = new Agent({
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+})
+```
+
+### Using Application Default Credentials
+
+If running on Google Cloud or with `gcloud` CLI configured, you can omit credentials:
+
+```typescript
+import { GCSFilesystem } from '@mastra/gcs'
+
+const filesystem = new GCSFilesystem({
+  bucket: 'my-gcs-bucket',
+  // Uses Application Default Credentials automatically
+})
+```
+
+[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) automatically discovers credentials in this order:
+
+1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to a service account key file)
+2. Default service account when running on GCP (Compute Engine, Cloud Run, GKE, etc.)
+3. User credentials from `gcloud auth application-default login` (for local development)
+
+### Using a Key File Path
+
+You can also pass a path to a service account key file:
+
+```typescript
+import { GCSFilesystem } from '@mastra/gcs'
+
+const filesystem = new GCSFilesystem({
+  bucket: 'my-gcs-bucket',
+  projectId: 'my-project-id',
+  credentials: '/path/to/service-account-key.json',
+})
+```
+
+## Constructor parameters
+
+**bucket:** (`string`): GCS bucket name
+
+**projectId?:** (`string`): GCS project ID. Required when using service account credentials.
+
+**credentials?:** (`object | string`): Service account key JSON object or path to key file. If not provided, uses Application Default Credentials.
+
+**prefix?:** (`string`): Optional prefix for all keys (acts like a subdirectory)
+
+**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
+
+**displayName?:** (`string`): Human-friendly display name for the UI
+
+**icon?:** (`FilesystemIcon`): Icon identifier for the UI
+
+**description?:** (`string`): Short description of this filesystem for the UI
+
+**readOnly?:** (`boolean`): When true, all write operations are blocked (Default: `false`)
+
+**endpoint?:** (`string`): Custom API endpoint URL. Used for local development with emulators.
+
+## Properties
+
+**id:** (`string`): Filesystem instance identifier
+
+**name:** (`string`): Provider name ('GCSFilesystem')
+
+**provider:** (`string`): Provider identifier ('gcs')
+
+**bucket:** (`string`): The GCS bucket name
+
+**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
+
+## Methods
+
+GCSFilesystem implements the [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem), providing all standard filesystem methods:
+
+- `readFile(path, options?)` - Read file contents
+- `writeFile(path, content, options?)` - Write content to a file
+- `appendFile(path, content)` - Append content to a file
+- `deleteFile(path, options?)` - Delete a file
+- `copyFile(src, dest, options?)` - Copy a file
+- `moveFile(src, dest, options?)` - Move or rename a file
+- `mkdir(path, options?)` - Create a directory
+- `rmdir(path, options?)` - Remove a directory
+- `readdir(path, options?)` - List directory contents
+- `exists(path)` - Check if a path exists
+- `stat(path)` - Get file or directory metadata
+
+### `init()`
+
+Initialize the filesystem. Verifies bucket access and credentials.
+
+```typescript
+await filesystem.init()
+```
+
+### `getInfo()`
+
+Returns metadata about this filesystem instance.
+
+```typescript
+const info = filesystem.getInfo()
+// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
+```
+
+### `getMountConfig()`
+
+Returns the mount configuration for sandboxes that support mounting this filesystem type.
+
+```typescript
+const config = filesystem.getMountConfig()
+// { type: 'gcs', bucket: 'my-bucket', ... }
+```
+
+## Mounting in E2B Sandboxes
+
+GCSFilesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { GCSFilesystem } from '@mastra/gcs'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new GCSFilesystem({
+      bucket: 'my-gcs-bucket',
+      projectId: 'my-project-id',
+      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+See [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox) for more details on mounting.
+
+## Related
+
+- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)