@mastra/core 1.1.0-alpha.0 → 1.1.0-alpha.1

package/dist/docs/agents/01-overview.md

@@ -1,8 +1,8 @@
 > Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
 
 # Using Agents
 

package/dist/docs/evals/01-overview.md

@@ -1,11 +1,11 @@
 > Overview of scorers in Mastra, detailing their capabilities for evaluating AI outputs and measuring performance.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
-- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:8275
-- `createStep`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:7615
-- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-REH5FX2O.js:8291
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
+- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:8275
+- `createStep`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:7615
+- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-SFICZTYL.js:8291
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
 
 # Scorers overview
 

package/dist/docs/mcp/01-overview.md

@@ -1,8 +1,8 @@
 > Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
 
 # MCP Overview
 

package/dist/docs/observability/01-overview.md

@@ -1,7 +1,7 @@
 > Monitor and debug applications with Mastra
 
 > **Code References:**
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
 
 # Observability Overview
 

package/dist/docs/observability/03-overview.md

@@ -1,9 +1,9 @@
 > Set up Tracing for Mastra applications
 
 > **Code References:**
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
-- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-REH5FX2O.js:8291
-- `Run`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:9121
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
+- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-SFICZTYL.js:8291
+- `Run`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:9121
 
 # Tracing
 

package/dist/docs/rag/01-overview.md

@@ -1,7 +1,7 @@
 > Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
 
 > **Code References:**
-- `ModelRouterEmbeddingModel`: dist/llm/index.d.ts → dist/chunk-5BEYS33K.js:4851
+- `ModelRouterEmbeddingModel`: dist/llm/index.d.ts → dist/chunk-RQGER4J4.js:4851
 
 # RAG (Retrieval-Augmented Generation) in Mastra
 

package/dist/docs/tools-mcp/01-mcp-overview.md

@@ -1,8 +1,8 @@
 > Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
 
 # MCP Overview
 

package/dist/docs/voice/01-overview.md

@@ -1,7 +1,7 @@
 > Overview of voice capabilities in Mastra, including text-to-speech, speech-to-text, and real-time speech-to-speech interactions.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
 - `CompositeVoice`: dist/voice/index.d.ts → dist/chunk-MQB7XFXP.js:192
 
 # Voice in Mastra

package/dist/docs/workflows/01-overview.md

@@ -1,11 +1,11 @@
 > Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more.
 
 > **Code References:**
-- `createStep`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:7615
-- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:8275
-- `cloneWorkflow`: dist/workflows/index.d.ts → dist/chunk-REH5FX2O.js:8278
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
-- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-REH5FX2O.js:8291
+- `createStep`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:7615
+- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:8275
+- `cloneWorkflow`: dist/workflows/index.d.ts → dist/chunk-SFICZTYL.js:8278
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
+- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-SFICZTYL.js:8291
 
 # Workflows overview
 

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

@@ -1,8 +1,8 @@
 > Give agents filesystem access and code execution through workspaces.
 
 > **Code References:**
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-5VWOGZLE.js:24
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-REH5FX2O.js:17501
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-HKD4NSHR.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-SFICZTYL.js:17504
 
 # Workspace
 
@@ -10,15 +10,16 @@ A workspace gives agents a persistent environment for storing files and executin
 
 ## How Workspaces Work
 
-A workspace combines up to three components:
+A workspace supports the following features:
 
-- **[Filesystem provider](https://mastra.ai/docs/workspace/filesystem)** - Handles file storage (read, write, list, delete)
-- **[Sandbox provider](https://mastra.ai/docs/workspace/sandbox)** - Handles command execution (shell commands)
+- **[Filesystem](https://mastra.ai/docs/workspace/filesystem)** - File storage (read, write, list, delete)
+- **[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
 
 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 as part of its task.
 
-You can create a workspace with any combination of these components. The agent receives only the tools relevant to what's configured.
+You can create a workspace with any combination of these features. The agent receives only the tools relevant to what's configured.
 
 ## Creating a Workspace
 
@@ -36,29 +37,6 @@ const workspace = new Workspace({
 });
 ```
 
-## Initialization
-
-You can optionally call `init()` to initialize the workspace before use:
-
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
-});
-
-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 working directory
-- **Search**: Indexes files from `autoIndexPaths` (if configured)
-
-External providers may perform additional setup like establishing connections or authenticating.
-
 ## Global Workspace
 
 Set a workspace on the Mastra instance. All agents inherit this workspace unless they define their own:
@@ -96,6 +74,31 @@ export const myAgent = new Agent({
 });
 ```
 
+## Initialization
+
+You can optionally call `init()` to initialize the workspace before use:
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+});
+
+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 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.
+
 ## Tool Configuration
 
 Configure tool behavior through the `tools` option on the Workspace. This controls which tools are enabled and their safety settings.

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

@@ -27,7 +27,10 @@ LocalFilesystem is the simplest way to get started - it requires no external ser
 
 ## 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({
@@ -35,6 +38,16 @@ const workspace = new Workspace({
     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');
 ```
 
 ## Read-only mode

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

@@ -24,9 +24,10 @@ Each provider page includes configuration options and usage examples:
 
 ## Basic usage
 
-Create a workspace with a sandbox and execute commands:
+Create a workspace with a sandbox 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({
@@ -38,9 +39,15 @@ const workspace = new Workspace({
   }),
 });
 
-// Execute a command
-const result = await workspace.sandbox.executeCommand('ls', ['-la']);
-console.log(result.stdout);
+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.

package/dist/docs/workspace/05-search.md

@@ -50,7 +50,7 @@ For custom BM25 parameters:
 const workspace = new Workspace({
   filesystem: new LocalFilesystem({ basePath: './workspace' }),
   bm25: {
-    k1: 1.2,   // Term frequency saturation (default: 1.2)
+    k1: 1.5,   // Term frequency saturation (default: 1.5)
     b: 0.75,  // Document length normalization (default: 0.75)
   },
 });

package/dist/docs/workspace/06-reference.md

@@ -304,12 +304,26 @@ npm install @mastra/core@latest
 
 ## 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 { LocalFilesystem } from '@mastra/core/workspace';
+import { Agent } from '@mastra/core/agent';
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
 
-const filesystem = new LocalFilesystem({
-  basePath: './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
@@ -318,6 +332,166 @@ const filesystem = new LocalFilesystem({
 
 ## Methods
 
+### `init()`
+
+Initialize the filesystem. Creates the base directory if it doesn't exist.
+
+```typescript
+await filesystem.init();
+```
+
+Called by `workspace.init()`.
+
+### `destroy()`
+
+Clean up filesystem resources.
+
+```typescript
+await filesystem.destroy();
+```
+
+Called by `workspace.destroy()`.
+
+### `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:**
+
+**Returns:** `Promise<string | Buffer>`
+
+### `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:**
+
+### `appendFile(path, content)`
+
+Append content to an existing file.
+
+```typescript
+await filesystem.appendFile('/logs/app.log', 'New log entry\n');
+```
+
+**Parameters:**
+
+### `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:**
+
+### `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:**
+
+### `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:**
+
+### `mkdir(path, options?)`
+
+Create a directory.
+
+```typescript
+await filesystem.mkdir('/docs/api');
+await filesystem.mkdir('/deeply/nested/path', { recursive: true });
+```
+
+**Parameters:**
+
+### `rmdir(path, options?)`
+
+Remove a directory.
+
+```typescript
+await filesystem.rmdir('/docs/old');
+await filesystem.rmdir('/docs/nested', { recursive: true });
+```
+
+**Parameters:**
+
+### `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;
+  modifiedAt?: Date;
+}
+```
+
+### `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');
+// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
+```
+
+**Returns:** `Promise<FileStat>`
+
+```typescript
+interface FileStat {
+  type: 'file' | 'directory';
+  size: number;
+  modifiedAt: Date;
+  createdAt: Date;
+  path: string;
+}
+```
+
 ### `getInfo()`
 
 Returns metadata about this filesystem instance.
@@ -327,6 +501,18 @@ const info = filesystem.getInfo();
 // { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
 ```
 
+**Returns:** `FilesystemInfo`
+
+```typescript
+interface FilesystemInfo {
+  id: string;
+  name: string;
+  provider: string;
+  basePath?: string;
+  readOnly?: boolean;
+}
+```
+
 ### `getInstructions()`
 
 Returns a description of how paths work in this filesystem. Used in tool descriptions.
@@ -336,6 +522,8 @@ const instructions = filesystem.getInstructions();
 // 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
 ```
 
+**Returns:** `string`
+
 ## Path Resolution
 
 ### How basePath works
@@ -410,23 +598,35 @@ npm install @mastra/core@latest
 
 ## 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 { LocalSandbox } from '@mastra/core/workspace';
+import { Agent } from '@mastra/core/agent';
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
 
-const sandbox = new LocalSandbox({
-  workingDirectory: './workspace',
-  env: {
-    NODE_ENV: 'development',
-  },
+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,
 });
 
-// Execute a command (auto-starts if not already running)
-const result = await sandbox.executeCommand('echo', ['hello']);
+// 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 `executeCommand()` call if not already running. You can also explicitly start the sandbox by calling `workspace.init()` at application startup to avoid first-command latency.
+`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
 
@@ -438,6 +638,96 @@ Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'
 
 ## 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'
+```
+
+**Returns:** `Promise<boolean>`
+
+### `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:**
+
+**Returns:** `Promise<CommandResult>`
+
+```typescript
+interface CommandResult {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  executionTimeMs: number;
+}
+```
+
+### `getInfo()`
+
+Get sandbox status and resource information.
+
+```typescript
+const info = await sandbox.getInfo();
+// { status: 'running', resources: { ... } }
+```
+
+**Returns:** `Promise<SandboxInfo>`
+
+```typescript
+interface SandboxInfo {
+  status: 'starting' | 'running' | 'stopped' | 'error';
+  resources?: {
+    memoryMB?: number;
+    memoryUsedMB?: number;
+    cpuCores?: number;
+    cpuPercent?: number;
+    diskMB?: number;
+    diskUsedMB?: number;
+  };
+}
+```
+
 ### `getInstructions()`
 
 Returns a description of how this sandbox works. Used in tool descriptions.
@@ -447,6 +737,8 @@ const instructions = sandbox.getInstructions();
 // 'Local command execution. Working directory: "/workspace".'
 ```
 
+**Returns:** `string`
+
 ## Path Resolution
 
 ### Relative paths and execution context