npm - @mastra/core - Versions diffs - 1.6.0 → 1.7.0-alpha.0 - Mend

@mastra/core 1.6.0 → 1.7.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (452) hide show

package/dist/docs/references/reference-workspace-local-filesystem.md DELETED Viewed

@@ -1,327 +0,0 @@
-# LocalFilesystem
-**Added in:** `@mastra/core@1.1.0`
-Stores files in a directory on the local filesystem.
-> **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
-## Usage
-Add a `LocalFilesystem` to a workspace 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',
-  workspace,
-});
-// The agent now has filesystem tools available
-const response = await agent.generate('List all files in the workspace');
-```
-## Constructor parameters
-**basePath:** (`string`): Base directory path on disk. All file paths are resolved relative to this directory.
-**id?:** (`string`): Unique identifier for this filesystem instance (Default: `Auto-generated`)
-**contained?:** (`boolean`): When true, all file operations are restricted to stay within basePath. Prevents path traversal attacks and symlink escapes. See \[containment]\(/docs/workspace/filesystem#containment). (Default: `true`)
-**allowedPaths?:** (`string[]`): Additional absolute paths that are allowed beyond basePath. Useful with \`contained: true\` to grant access to specific directories without disabling containment entirely. Paths are resolved to absolute paths. (Default: `[]`)
-**readOnly?:** (`boolean`): When true, all write operations are blocked. Read operations are still allowed. (Default: `false`)
-## Properties
-**id:** (`string`): Filesystem instance identifier
-**name:** (`string`): Provider name ('LocalFilesystem')
-**provider:** (`string`): Provider identifier ('local')
-**basePath:** (`string`): The absolute base path on disk
-**readOnly:** (`boolean | undefined`): Whether the filesystem is in read-only mode
-**allowedPaths:** (`readonly string[]`): Current set of additional allowed paths (absolute, resolved). These paths are permitted beyond basePath when containment is enabled.
-## Methods
-### `init()`
-Initialize the filesystem. Creates the base directory if it doesn't exist.
-```typescript
-await filesystem.init();
-```
-Called by `workspace.init()`.
-### Lazy initialization
-LocalFilesystem initializes on first operation if not already initialized, creating the base directory automatically. Calling `init()` explicitly is optional but can be useful to pre-create directories before the first operation.
-### `destroy()`
-Clean up filesystem resources.
-```typescript
-await filesystem.destroy();
-```
-Called by `workspace.destroy()`.
-### `setAllowedPaths(pathsOrUpdater)`
-Update the allowed paths at runtime. Accepts a new paths array (replaces current) or an updater callback that receives the current paths and returns the new set.
-```typescript
-// Set directly
-filesystem.setAllowedPaths(['/home/user/.config']);
-// Update with callback
-filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents']);
-// Clear all allowed paths
-filesystem.setAllowedPaths([]);
-```
-**Parameters:**
-**pathsOrUpdater:** (`string[] | ((current: readonly string[]) => string[])`): New allowed paths array or updater function receiving current paths
-### `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'`)
-### `writeFile(path, content, options?)`
-Write content to a file.
-```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`)
-### `appendFile(path, content)`
-Append content to an existing file.
-```typescript
-await filesystem.appendFile('/logs/app.log', 'New log entry\n');
-```
-**Parameters:**
-**path:** (`string`): File path relative to basePath
-**content:** (`string | Buffer`): Content to append
-### `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`)
-### `copyFile(src, dest, options?)`
-Copy a file to a new location.
-```typescript
-await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md');
-await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite: false });
-```
-**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');
-await filesystem.moveFile('/temp/upload.txt', '/files/document.txt');
-```
-**Parameters:**
-**src:** (`string`): Source file path
-**dest:** (`string`): Destination file path
-**options.overwrite?:** (`boolean`): Overwrite destination if it exists (Default: `true`)
-### `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`)
-### `readdir(path, options?)`
-List directory contents.
-```typescript
-const entries = await filesystem.readdir('/docs');
-// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
-```
-### `exists(path)`
-Check if a path exists.
-```typescript
-const exists = await filesystem.exists('/docs/guide.md');
-```
-### `stat(path)`
-Get file or directory metadata.
-```typescript
-const stat = await filesystem.stat('/docs/guide.md');
-// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
-```
-### `getInfo()`
-Returns metadata about this filesystem instance.
-```typescript
-const info = filesystem.getInfo();
-// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
-```
-### `getInstructions()`
-Returns a description of how paths work in this filesystem. Used in tool descriptions.
-```typescript
-const instructions = filesystem.getInstructions();
-// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
-```
-## Path resolution
-### How basePath works
-The `basePath` option sets the root directory for all file operations. File paths passed to methods like `readFile()` are resolved relative to this base:
-- Leading slashes are stripped: `/docs/guide.md` → `docs/guide.md`
-- The path is normalized and joined with basePath
-- Result: `./workspace` + `docs/guide.md` → `./workspace/docs/guide.md`
-```typescript
-const filesystem = new LocalFilesystem({
-  basePath: './workspace',
-});
-// These all resolve to ./workspace/docs/guide.md
-await filesystem.readFile('/docs/guide.md');
-await filesystem.readFile('docs/guide.md');
-```
-### Relative paths and execution context
-When you use a relative path for `basePath`, it resolves from `process.cwd()`. In Mastra projects, cwd varies depending on how you run your code:
-| Context        | Working directory         | `./workspace` resolves to       |
-| -------------- | ------------------------- | ------------------------------- |
-| `mastra dev`   | `./src/mastra/public/`    | `./src/mastra/public/workspace` |
-| `mastra start` | `./.mastra/output/`       | `./.mastra/output/workspace`    |
-| Direct script  | Where you ran the command | Relative to that location       |
-This can cause confusion when the same relative path resolves to different locations.
-### Recommended: Use absolute paths
-For consistent paths across all execution contexts, use an environment variable with an absolute path:
-```typescript
-import { LocalFilesystem } from '@mastra/core/workspace';
-const filesystem = new LocalFilesystem({
-  basePath: process.env.WORKSPACE_PATH!,
-});
-```
-Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my-project/workspace`. This ensures the workspace path is consistent regardless of how you run your code.
-## Related
-- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
-- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/dist/docs/references/reference-workspace-local-sandbox.md DELETED Viewed

@@ -1,285 +0,0 @@
-# LocalSandbox
-**Added in:** `@mastra/core@1.1.0`
-Executes commands on the local system.
-> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
-## Usage
-Add a `LocalSandbox` to a workspace and assign it to an agent. The agent can then execute shell commands as part of its tasks:
-```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',
-    env: {
-      NODE_ENV: 'development',
-    },
-  }),
-});
-const agent = new Agent({
-  id: 'dev-agent',
-  model: 'openai/gpt-4o',
-  workspace,
-});
-// The agent now has the execute_command tool available
-const response = await agent.generate('Run npm install');
-```
-### Auto-start behavior
-`LocalSandbox` automatically starts on the first command execution if not already running. You can also explicitly start the sandbox by calling `workspace.init()` at application startup to avoid first-command latency.
-## Constructor parameters
-**id?:** (`string`): Unique identifier for this sandbox instance (Default: `Auto-generated`)
-**workingDirectory?:** (`string`): Directory for command execution. Defaults to .sandbox/ in process.cwd() for isolation from seatbelt profiles. (Default: `process.cwd()/.sandbox/`)
-**env?:** (`NodeJS.ProcessEnv`): Environment variables to set. PATH is included by default unless overridden.
-**timeout?:** (`number`): Default timeout for operations in milliseconds (Default: `30000`)
-**isolation?:** (`'none' | 'seatbelt' | 'bwrap'`): Native OS sandboxing backend. 'seatbelt' for macOS, 'bwrap' for Linux. (Default: `'none'`)
-**nativeSandbox?:** (`NativeSandboxConfig`): Configuration for native sandboxing (see NativeSandboxConfig below).
-## NativeSandboxConfig
-Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'` or `'bwrap'`).
-**allowNetwork?:** (`boolean`): Allow network access from sandboxed commands. (Default: `false`)
-**readOnlyPaths?:** (`string[]`): Additional paths to allow read-only access (system paths are always readable).
-**readWritePaths?:** (`string[]`): Additional paths to allow read-write access beyond the workspace directory.
-**seatbeltProfilePath?:** (`string`): Path to a custom seatbelt profile file (macOS only). If the file exists, it's used; if not, a default profile is generated and written to this path.
-**bwrapArgs?:** (`string[]`): Additional arguments to pass to bwrap (Linux only).
-**allowSystemBinaries?:** (`boolean`): Allow read access to standard system binary paths (/bin, /usr/bin, etc.). (Default: `true`)
-## Properties
-**id:** (`string`): Sandbox instance identifier
-**name:** (`string`): Provider name ('LocalSandbox')
-**provider:** (`string`): Provider identifier ('local')
-**status:** (`ProviderStatus`): 'starting' | 'running' | 'stopped' | 'error'
-**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()`
-Returns a description of how this sandbox works. Used in tool descriptions.
-```typescript
-const instructions = sandbox.getInstructions();
-// 'Local command execution. Working directory: "/workspace".'
-```
-## Path Resolution
-### Relative paths and execution context
-When you use a relative path for `workingDirectory`, it resolves from `process.cwd()`. In Mastra projects, cwd varies depending on how you run your code:
-| Context        | Working directory         | `./workspace` resolves to       |
-| -------------- | ------------------------- | ------------------------------- |
-| `mastra dev`   | `./src/mastra/public/`    | `./src/mastra/public/workspace` |
-| `mastra start` | `./.mastra/output/`       | `./.mastra/output/workspace`    |
-| Direct script  | Where you ran the command | Relative to that location       |
-This can cause confusion when the same relative path resolves to different locations.
-### Recommended: Use absolute paths
-For consistent paths across all execution contexts, use an environment variable with an absolute path:
-```typescript
-import { LocalSandbox } from '@mastra/core/workspace';
-const sandbox = new LocalSandbox({
-  workingDirectory: process.env.WORKSPACE_PATH!,
-});
-```
-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
-### `detectIsolation()`
-Detect the best available isolation backend for the current platform.
-```typescript
-const detection = LocalSandbox.detectIsolation();
-// { backend: 'seatbelt', available: true, message: 'Seatbelt available on macOS' }
-```
-## 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.
-```typescript
-// Default: only PATH is available (commands work, secrets protected)
-const secureSandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-});
-// Explicit: pass specific variables
-const sandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  env: {
-    NODE_ENV: 'development',
-    API_URL: 'https://api.example.com',
-  },
-});
-// Full access (use with caution)
-const devSandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  env: process.env,
-});
-```
-## Native OS Sandboxing
-`LocalSandbox` supports native OS-level sandboxing for additional security:
-- **macOS**: Uses Seatbelt (`sandbox-exec`) for filesystem and network isolation
-- **Linux**: Uses Bubblewrap (`bwrap`) for namespace isolation
-```typescript
-// Detect the best available backend for this platform
-const detection = LocalSandbox.detectIsolation();
-console.log(detection);
-// { backend: 'seatbelt', available: true, message: '...' }
-// Enable native sandboxing
-const sandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  isolation: 'seatbelt', // or 'bwrap' on Linux
-  nativeSandbox: {
-    allowNetwork: false, // Block network access (default)
-    readWritePaths: ['/tmp/extra'], // Additional writable paths
-  },
-});
-```
-When isolation is enabled:
-- File writes are restricted to the workspace directory (and configured paths)
-- File reads are allowed everywhere (needed for system binaries)
-- Network access is blocked by default
-- Process isolation prevents affecting the host system
-### Sandbox profile location
-When using seatbelt isolation on macOS, `LocalSandbox` generates a profile file in a `.sandbox-profiles/` folder in `process.cwd()`, separate from the working directory:
-```text
-project/
-├── .sandbox/                      # Default working directory (sandboxed)
-│   └── ... files created by sandbox
-├── .sandbox-profiles/             # Seatbelt profiles (outside sandbox)
-│   └── seatbelt-a1b2c3d4.sb       # Hash based on workspace + config
-└── ... your project files
-```
-The profile filename is a hash of the workspace path and configuration, so sandboxes with identical settings share the same profile while different configurations get separate files. This prevents collisions when running multiple sandboxes concurrently.
-This separation prevents sandboxed processes from reading or modifying their own security profiles. The profile is created when the sandbox starts and cleaned up when destroyed.
-## Related
-- [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/dist/docs/references/reference-workspace-sandbox.md DELETED Viewed

@@ -1,81 +0,0 @@
-# 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()`
-Get a description of how this sandbox works. Used in tool descriptions to help agents understand the execution context.
-```typescript
-const instructions = sandbox.getInstructions?.();
-// 'Local command execution. Working directory: "/workspace".'
-```
-## Related
-- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Filesystem Interface](https://mastra.ai/reference/workspace/filesystem)