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

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

@@ -0,0 +1,177 @@
+# S3Filesystem
+
+Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
+
+> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
+
+## Installation
+
+```bash
+npm install @mastra/s3
+```
+
+## Usage
+
+Add an `S3Filesystem` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+
+const workspace = new Workspace({
+  filesystem: new S3Filesystem({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  }),
+})
+
+const agent = new Agent({
+  name: 'file-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+})
+```
+
+### Cloudflare R2
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+const filesystem = new S3Filesystem({
+  bucket: 'my-r2-bucket',
+  region: 'auto',
+  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+  accessKeyId: process.env.R2_ACCESS_KEY_ID,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+})
+```
+
+### MinIO
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+const filesystem = new S3Filesystem({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  endpoint: 'http://localhost:9000',
+  accessKeyId: 'minioadmin',
+  secretAccessKey: 'minioadmin',
+})
+```
+
+## Constructor parameters
+
+**bucket:** (`string`): S3 bucket name
+
+**region:** (`string`): AWS region (use 'auto' for R2)
+
+**accessKeyId?:** (`string`): AWS access key ID. Optional for public buckets (read-only access).
+
+**secretAccessKey?:** (`string`): AWS secret access key. Optional for public buckets (read-only access).
+
+**sessionToken?:** (`string`): AWS session token for temporary credentials. Required when using SSO, AssumeRole, container credentials, or any other temporary credential provider.
+
+**endpoint?:** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, etc.)
+
+**forcePathStyle?:** (`boolean`): Force path-style URLs instead of virtual-hosted-style. Required for some S3-compatible services like MinIO. Defaults to true when a custom endpoint is provided. (Default: `true (when endpoint is set)`)
+
+**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`)
+
+## Properties
+
+**id:** (`string`): Filesystem instance identifier
+
+**name:** (`string`): Provider name ('S3Filesystem')
+
+**provider:** (`string`): Provider identifier ('s3')
+
+**bucket:** (`string`): The S3 bucket name
+
+**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
+
+## Methods
+
+S3Filesystem 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: 'S3Filesystem', provider: 's3', status: 'ready' }
+```
+
+### `getMountConfig()`
+
+Returns the mount configuration for sandboxes that support mounting this filesystem type.
+
+```typescript
+const config = filesystem.getMountConfig()
+// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
+```
+
+## Mounting in E2B Sandboxes
+
+S3Filesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { S3Filesystem } from '@mastra/s3'
+import { E2BSandbox } from '@mastra/e2b'
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_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)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -0,0 +1,87 @@
+# WorkspaceSandbox
+
+**Added in:** `@mastra/core@1.1.0`
+
+The `WorkspaceSandbox` interface defines how workspaces execute commands.
+
+## Methods
+
+### `start()`
+
+Start the sandbox. Called automatically by `workspace.init()` or on first `executeCommand()` call.
+
+```typescript
+await sandbox.start()
+```
+
+This method prepares the sandbox for command execution.
+
+### `stop()`
+
+Stop the sandbox.
+
+```typescript
+await sandbox.stop?.()
+```
+
+### `destroy()`
+
+Clean up sandbox resources. Called by `workspace.destroy()`.
+
+```typescript
+await sandbox.destroy()
+```
+
+### `executeCommand(command, args?, options?)`
+
+Execute a shell command.
+
+```typescript
+const result = await sandbox.executeCommand('ls', ['-la', '/docs'])
+const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
+```
+
+**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: { memoryMB: 512, cpuPercent: 5 } }
+```
+
+### `getInstructions(opts?)`
+
+Returns a description of how this sandbox works. Injected into the agent's system message when the workspace is assigned to an agent.
+
+```typescript
+const instructions = sandbox.getInstructions?.()
+// 'Local command execution. Working directory: "/workspace".'
+```
+
+**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)
+- [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem)

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

@@ -0,0 +1,244 @@
+# Workspace Class
+
+**Added in:** `@mastra/core@1.1.0`
+
+The `Workspace` class combines a filesystem and sandbox to provide agents with file storage and command execution capabilities. It also supports BM25 and vector search for indexed content.
+
+## Usage Example
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  id: 'my-workspace',
+  name: 'My Workspace',
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+  }),
+  sandbox: new LocalSandbox({
+    workingDirectory: './workspace',
+  }),
+  bm25: true,
+  autoIndexPaths: ['/docs'],
+})
+```
+
+## Constructor parameters
+
+**id?:** (`string`): Unique identifier for the workspace (Default: `Auto-generated`)
+
+**name?:** (`string`): Human-readable name (Default: `workspace-{id}`)
+
+**filesystem?:** (`WorkspaceFilesystem`): Filesystem provider instance (e.g., LocalFilesystem)
+
+**sandbox?:** (`WorkspaceSandbox`): Sandbox provider instance (e.g., LocalSandbox)
+
+**bm25?:** (`boolean | BM25Config`): Enable BM25 keyword search. Pass true for defaults or a config object. (Default: `undefined`)
+
+**vectorStore?:** (`MastraVector`): Vector store for semantic search
+
+**embedder?:** (`(text: string) => Promise<number[]>`): Embedder function for generating vectors. Required when vectorStore is provided.
+
+**autoIndexPaths?:** (`string[]`): Paths or glob patterns to auto-index on init(). Supports glob patterns like '\*\*/\*.md' for selective indexing.
+
+**skills?:** (`string[] | ((context: SkillsContext) => string[] | Promise<string[]>)`): Paths where SKILL.md files are located. This can be a static array or an async function that resolves paths dynamically. Supports glob patterns like './\*\*/skills' for discovery.
+
+**skillSource?:** (`SkillSource`): Custom skill source for skill discovery. When provided, this source is used instead of the workspace filesystem. Use VersionedSkillSource to serve published skill versions from a content-addressable blob store.
+
+**onMount?:** (`OnMountHook`): Pre-mount hook called for each filesystem before mounting into a sandbox. Return false to skip mounting, or return { success: true } if the hook handled the mount. Return undefined to use the default mount behavior.
+
+**searchIndexName?:** (`string`): Custom index name for the vector store. Must be a valid SQL identifier (start with a letter or underscore, contain only letters, numbers, or underscores, max 63 characters). Defaults to a sanitized version of '{id}\_search'.
+
+**tools?:** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options
+
+**operationTimeout?:** (`number`): Timeout for operations in milliseconds
+
+## Tool configuration
+
+The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings.
+
+```typescript
+import { WORKSPACE_TOOLS } from '@mastra/core/workspace';
+
+tools: {
+  // Global defaults (apply to all tools)
+  enabled: true,
+  requireApproval: false,
+
+  // Per-tool overrides using WORKSPACE_TOOLS constants
+  [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
+    requireApproval: true,
+  },
+}
+```
+
+The config object has two parts:
+
+- **Global defaults** (`enabled`, `requireApproval`) - Apply to all tools unless overridden
+- **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
+
+See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples.
+
+### Per-tool options
+
+Each tool can be configured with these options:
+
+**enabled?:** (`boolean`): Whether the tool is available to agents (Default: `true`)
+
+**requireApproval?:** (`boolean`): Whether the tool requires user approval before execution (Default: `false`)
+
+**requireReadBeforeWrite?:** (`boolean`): For write tools: require reading the file first to prevent overwrites (Default: `false`)
+
+## Properties
+
+**id:** (`string`): Workspace identifier
+
+**name:** (`string`): Workspace name
+
+**status:** (`WorkspaceStatus`): 'pending' | 'initializing' | 'ready' | 'paused' | 'error' | 'destroying' | 'destroyed'
+
+**filesystem:** (`WorkspaceFilesystem | undefined`): The filesystem provider
+
+**sandbox:** (`WorkspaceSandbox | undefined`): The sandbox provider
+
+**skills:** (`WorkspaceSkills | undefined`): Skills interface for accessing SKILL.md files
+
+**canBM25:** (`boolean`): Whether BM25 search is available
+
+**canVector:** (`boolean`): Whether vector search is available
+
+**canHybrid:** (`boolean`): Whether hybrid search is available
+
+## Methods
+
+### Lifecycle
+
+#### `init()`
+
+Initialize the workspace and prepare resources.
+
+```typescript
+await workspace.init()
+```
+
+Calling `init()` is optional in most cases:
+
+- **Sandbox**: Auto-starts on first `executeCommand()` call. Use `init()` to avoid first-command latency.
+- **Filesystem**: Creates the base directory and runs any provider-specific setup. Some providers auto-create the directory on first operation.
+- **Search**: Required only if using `autoIndexPaths` for auto-indexing.
+
+Initialization performs:
+
+- Starts the filesystem provider (creates base directory if needed)
+- Starts the sandbox provider (creates working directory, sets up isolation if configured)
+- Indexes files from `autoIndexPaths` for search
+
+#### `destroy()`
+
+Destroy the workspace and clean up resources.
+
+```typescript
+await workspace.destroy()
+```
+
+### Search operations
+
+#### `index(path, content, options?)`
+
+Index content for search.
+
+```typescript
+await workspace.index('/docs/guide.md', 'Guide content...')
+```
+
+#### `search(query, options?)`
+
+Search indexed content.
+
+```typescript
+const results = await workspace.search('password reset', {
+  topK: 10,
+  mode: 'hybrid',
+})
+```
+
+### Utility
+
+#### `getInfo()`
+
+Get workspace information.
+
+```typescript
+const info = await workspace.getInfo()
+// { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? }
+```
+
+#### `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.
+
+```typescript
+const instructions = workspace.getInstructions()
+```
+
+Pass `requestContext` to enable per-request customization when a provider's `instructions` option is a function:
+
+```typescript
+const instructions = workspace.getInstructions({ requestContext })
+```
+
+**Parameters:**
+
+**opts.requestContext?:** (`RequestContext`): Forwarded to the \`instructions\` function on the filesystem or sandbox provider, if one is configured.
+
+**Returns:** `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()`
+
+Get the tools configuration.
+
+```typescript
+const config = workspace.getToolsConfig()
+```
+
+## Agent tools
+
+A workspace provides tools to agents based on what is configured.
+
+### Filesystem tools
+
+Added when a filesystem is configured:
+
+| Tool                          | Description                                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `mastra_workspace_read_file`  | Read file contents. Supports optional line range for reading specific portions of large files.                      |
+| `mastra_workspace_write_file` | Create or overwrite a file with new content. Creates parent directories automatically.                              |
+| `mastra_workspace_edit_file`  | Edit an existing file by finding and replacing text. Useful for targeted changes without rewriting the entire file. |
+| `mastra_workspace_list_files` | List directory contents as a tree structure. Supports recursive listing with depth limits.                          |
+| `mastra_workspace_delete`     | Delete a file or directory. Supports recursive deletion for directories.                                            |
+| `mastra_workspace_file_stat`  | Get metadata about a file or directory including size, type, and modification time.                                 |
+| `mastra_workspace_mkdir`      | Create a directory. Creates parent directories automatically if they don't exist.                                   |
+| `mastra_workspace_grep`       | Search file contents using regex patterns. Supports glob filtering, context lines, and case-insensitive search.     |
+
+Write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode.
+
+### Sandbox tools
+
+Added when a sandbox is configured:
+
+| Tool                               | Description                                                                                                            |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `mastra_workspace_execute_command` | Execute a shell command with arguments. Returns stdout, stderr, and exit code. Supports timeouts and streaming output. |
+
+### Search tools
+
+Added when BM25 or vector search is configured:
+
+| Tool                      | Description                                                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `mastra_workspace_search` | Search indexed content using keyword (BM25), semantic (vector), or hybrid search. Returns ranked results with scores. |
+| `mastra_workspace_index`  | Index content for search. Associates content with a path for later retrieval.                                         |
+
+The `index` tool is excluded when the filesystem is in read-only mode.