@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-workspace-filesystem.md

@@ -0,0 +1,164 @@
+# Filesystem
+
+**Added in:** `@mastra/core@1.1.0`
+
+Filesystem providers give agents the ability to read, write, and manage files. When you configure a filesystem on a workspace, agents receive tools for file operations.
+
+A filesystem provider handles all file operations for a workspace:
+
+- **Read** - Read file contents
+- **Write** - Create and update files
+- **List** - Browse directories with optional glob pattern filtering
+- **Delete** - Remove files and directories
+- **Stat** - Get file metadata
+- **Copy/Move** - Copy or move files between locations
+- **Grep** - Search file contents using regex patterns
+
+## Supported providers
+
+Available providers:
+
+- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) - Stores files in a directory on disk
+- [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) - Stores files in Amazon S3 or S3-compatible storage (R2, MinIO)
+- [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem) - Stores files in Google Cloud Storage
+
+> **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services. For cloud storage, use `S3Filesystem` or `GCSFilesystem`.
+
+## Basic usage
+
+Create a workspace with a filesystem and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+  }),
+})
+
+const agent = new Agent({
+  id: 'file-agent',
+  model: 'openai/gpt-4o',
+  instructions: 'You are a helpful file management assistant.',
+  workspace,
+})
+
+// The agent now has filesystem tools available
+const response = await agent.generate('List all files in the workspace')
+```
+
+## Containment
+
+By default, `LocalFilesystem` runs in **contained mode** — all file operations are restricted to stay within `basePath`. This prevents path traversal attacks and symlink escapes.
+
+In contained mode, absolute paths that fall within `basePath` are used as-is, while other absolute paths are treated as virtual paths relative to `basePath` (e.g. `/file.txt` resolves to `basePath/file.txt`). Any resolved path that escapes `basePath` throws a `PermissionError`.
+
+If your agent needs to access specific paths outside `basePath`, use `allowedPaths` to grant access without disabling containment entirely:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+    allowedPaths: ['/home/user/.config', '/home/user/documents'],
+  }),
+})
+```
+
+Allowed paths can be updated at runtime using the `setAllowedPaths()` method:
+
+```typescript
+// Add a path dynamically
+workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])
+```
+
+This is the recommended approach for least-privilege access — the agent can only reach the specific directories you allow.
+
+If your agent needs unrestricted access to the entire filesystem, disable containment:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+    contained: false,
+  }),
+})
+```
+
+When `contained` is `false`, absolute paths are treated as real filesystem paths with no restriction.
+
+## Read-only mode
+
+To prevent agents from modifying files, enable read-only mode:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+    readOnly: true,
+  }),
+})
+```
+
+When read-only, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are not added to the agent's toolset. The agent can still read and list files.
+
+## Mounts and CompositeFilesystem
+
+When you use the `mounts` option on a workspace, Mastra creates a `CompositeFilesystem` that routes file operations to the correct provider based on path prefix.
+
+```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: {
+    '/data': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+    '/skills': new GCSFilesystem({
+      bucket: 'agent-skills',
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+With this configuration:
+
+- `read_file('/data/input.csv')` reads from the S3 bucket
+- `write_file('/skills/guide.md', content)` writes to the GCS bucket
+- `list_directory('/')` returns virtual entries for `/data` and `/skills`
+- Commands in the sandbox can access files at `/data` and `/skills` via FUSE mounts
+
+### Path routing
+
+All file paths must start with a mount prefix. Operations on paths that don't match any mount will fail. Listing the root directory (`/`) returns virtual directory entries for each mount point.
+
+Mount paths cannot be nested — for example, you cannot mount at both `/data` and `/data/sub`.
+
+### `filesystem` vs `mounts`
+
+`filesystem` and `mounts` are mutually exclusive options on a workspace:
+
+- Use **`filesystem`** when you have a single storage provider and don't need to mount it into a sandbox. The agent gets file tools that operate directly against the provider.
+- Use **`mounts`** when you need cloud storage accessible inside a sandbox, or when you want to combine multiple providers. The workspace creates a CompositeFilesystem for file tools and FUSE-mounts the storage into the sandbox.
+
+For local development, you typically don't need `mounts` — a `LocalFilesystem` and `LocalSandbox` pointed at the same directory gives you both file tools and command execution on the same files. See [configuration patterns](https://mastra.ai/docs/workspace/overview) for more detail.
+
+## Agent tools
+
+When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See [workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for details.
+
+## Related
+
+- [LocalFilesystem reference](https://mastra.ai/reference/workspace/local-filesystem)
+- [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)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/dist/docs/references/docs-workspace-overview.md

@@ -0,0 +1,239 @@
+# Workspaces
+
+**Added in:** `@mastra/core@1.1.0`
+
+A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents use workspace tools to read and write files, run shell commands, and search indexed content.
+
+A workspace supports the following features:
+
+- **[Filesystem](https://mastra.ai/docs/workspace/filesystem)**: File storage (read, write, list, delete, copy, move, grep)
+- **[Sandbox](https://mastra.ai/docs/workspace/sandbox)**: Command execution (shell commands)
+- **[Search](https://mastra.ai/docs/workspace/search)**: BM25, vector, or hybrid search over indexed content
+- **[Skills](https://mastra.ai/docs/workspace/skills)**: Reusable instructions for agents
+
+## How it works
+
+When you assign a workspace to an agent, Mastra includes the corresponding tools in the agent's toolset. The agent can then use these tools to interact with files and execute commands.
+
+You can create a workspace with any combination of the supported features. The agent receives only the tools relevant to what's configured.
+
+## Usage
+
+### Creating a workspace
+
+Create a workspace by instantiating the `Workspace` class with your desired features:
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+  }),
+  sandbox: new LocalSandbox({
+    workingDirectory: './workspace',
+  }),
+  skills: ['/skills'],
+})
+```
+
+The `skills` array specifies paths to directories containing skill definitions, see [Skills](https://mastra.ai/docs/workspace/skills).
+
+### Global workspace
+
+Set a workspace on the Mastra instance. All agents inherit this workspace unless they define their own:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+})
+
+const mastra = new Mastra({
+  workspace,
+})
+```
+
+### Agent-scoped workspace
+
+Assign a workspace directly to an agent to override the global workspace:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './agent-workspace' }),
+})
+
+export const myAgent = new Agent({
+  id: 'my-agent',
+  model: 'openai/gpt-4o',
+  workspace,
+})
+```
+
+## Configuration patterns
+
+Workspaces support several configuration patterns depending on what capabilities your agent needs. The two main building blocks are `filesystem` (file tools) and `sandbox` (command execution), with `mounts` as the way to bridge cloud storage into sandboxes.
+
+### Filesystem + sandbox (local)
+
+For local development, pair a `LocalFilesystem` and `LocalSandbox` pointed at the same directory. Since both operate on the local machine, files written through the filesystem are immediately available to commands in the sandbox:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+})
+```
+
+The agent receives both file tools and `execute_command`. This is the simplest full-featured setup.
+
+### Mounts + sandbox (cloud storage)
+
+When you need cloud storage accessible inside a sandbox, use `mounts`. This FUSE-mounts the cloud filesystem into the sandbox so commands can read and write files at the mount path:
+
+```typescript
+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,
+    }),
+    '/skills': new GCSFilesystem({
+      bucket: 'agent-skills',
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+Under the hood, `mounts` creates a [CompositeFilesystem](https://mastra.ai/docs/workspace/filesystem) that routes file tool operations to the correct provider based on path prefix. Commands in the sandbox access the mounted paths directly (e.g., `ls /data`).
+
+You can mount multiple providers at different paths. Each mount path must be unique and non-overlapping.
+
+> **Note:** `filesystem` and `mounts` are mutually exclusive — you cannot use both in the same workspace. Use `filesystem` for a single provider without a sandbox, or `mounts` when you need to combine cloud storage with a sandbox.
+
+### Filesystem only
+
+Use a single `filesystem` when agents only need to read and write files. No command execution is available.
+
+```typescript
+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,
+  }),
+})
+```
+
+The agent receives file tools (`read_file`, `write_file`, `list_directory`, `grep`, etc.) that operate directly against the storage provider.
+
+### Sandbox only
+
+Use a single `sandbox` when agents only need to execute commands. No file tools are added.
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+})
+```
+
+The agent receives the `execute_command` tool.
+
+### Which pattern should I use?
+
+| Scenario                                              | Pattern                                               |
+| ----------------------------------------------------- | ----------------------------------------------------- |
+| Local development with files and commands             | `filesystem` + `sandbox` (both local, same directory) |
+| Cloud storage accessible inside a cloud sandbox       | `mounts` + `sandbox`                                  |
+| Multiple cloud providers in one sandbox               | `mounts` + `sandbox` (one mount per provider)         |
+| Agent reads/writes files, no command execution needed | `filesystem` only                                     |
+| Agent runs commands, no file tools needed             | `sandbox` only                                        |
+
+## Tool configuration
+
+Configure tool behavior through the `tools` option on the workspace. This controls which tools are enabled and how they behave.
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  tools: {
+    // Global defaults
+    enabled: true,
+    requireApproval: false,
+
+    // Per-tool overrides
+    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
+      requireApproval: true,
+      requireReadBeforeWrite: true,
+    },
+    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: {
+      enabled: false,
+    },
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      requireApproval: true,
+    },
+  },
+})
+```
+
+### Tool options
+
+| Option                   | Type      | Description                                                                 |
+| ------------------------ | --------- | --------------------------------------------------------------------------- |
+| `enabled`                | `boolean` | Whether the tool is available (default: `true`)                             |
+| `requireApproval`        | `boolean` | Whether the tool requires user approval before execution (default: `false`) |
+| `requireReadBeforeWrite` | `boolean` | For write tools: require reading the file first (default: `false`)          |
+
+### Read-before-write
+
+When `requireReadBeforeWrite` is enabled on write tools, agents must read a file before writing to it. This prevents overwriting files the agent hasn't seen:
+
+- **New files**: Can be written without reading (they don't exist yet)
+- **Existing files**: Must be read first
+- **Externally modified files**: If a file changed since the agent read it, the write fails
+
+## Initialization
+
+Calling `init()` is optional in most cases—some providers initialize on first operation. Call `init()` manually when using a workspace outside of Mastra (standalone scripts, tests) or when you need to pre-provision resources before the first agent interaction.
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+})
+
+// Optional: pre-create directories and sandbox before first use
+await workspace.init()
+```
+
+### What init() does
+
+Initialization runs setup logic for each configured provider:
+
+- `LocalFilesystem`: Creates the base directory if it doesn't exist
+- `LocalSandbox`: Creates the working directory
+- `Search` (if configured): Indexes files from `autoIndexPaths`, see [Search and Indexing](https://mastra.ai/docs/workspace/search)
+
+External providers may perform additional setup like establishing connections or authenticating.
+
+## Related
+
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Skills](https://mastra.ai/docs/workspace/skills)
+- [Search and indexing](https://mastra.ai/docs/workspace/search)
+- [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/dist/docs/references/docs-workspace-sandbox.md

@@ -0,0 +1,63 @@
+# Sandbox
+
+**Added in:** `@mastra/core@1.1.0`
+
+Sandbox providers give agents the ability to execute shell commands. When you configure a sandbox on a workspace, agents can run commands as part of their tasks.
+
+A sandbox provider executes commands in a controlled environment:
+
+- **Command execution** - Run shell commands with arguments
+- **Working directory** - Commands run from a specific directory
+- **Environment variables** - Control what variables are available
+- **Timeouts** - Prevent long-running commands from hanging
+- **Isolation** - Optional OS-level sandboxing for security
+
+When you assign a workspace with a sandbox to an agent, Mastra automatically includes the `execute_command` tool in the agent's toolset.
+
+## Supported providers
+
+Available providers:
+
+- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) - Executes commands on the local machine
+- [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox) - Executes commands in isolated E2B cloud sandboxes
+
+## Basic usage
+
+Create a workspace with a sandbox and assign it to an agent. The agent can then execute shell commands:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+  }),
+  sandbox: new LocalSandbox({
+    workingDirectory: './workspace',
+  }),
+})
+
+const agent = new Agent({
+  id: 'dev-agent',
+  model: 'openai/gpt-4o',
+  instructions: 'You are a helpful development assistant.',
+  workspace,
+})
+
+// The agent now has the execute_command tool available
+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.
+
+## Agent tools
+
+When you configure a sandbox on a workspace, agents receive the `execute_command` tool for running shell commands. See [workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for details.
+
+## Related
+
+- [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem)