@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-workflows-workflow-methods-map.md

@@ -0,0 +1,93 @@
+# Workflow\.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage example
+
+```typescript
+workflow.map(async ({ inputData }) => `${inputData.value} - map`)
+```
+
+## Parameters
+
+**mappingFunction:** (`(params: { inputData: any }) => any`): Function that transforms input data and returns the mapped result
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Using `inputData`
+
+Use `inputData` to access the full output of the previous step.
+
+```typescript
+.then(step1)
+  .map(({ inputData }) => {
+    console.log(inputData);
+  })
+```
+
+## Using `getStepResult()`
+
+Use `getStepResult()` to access the full output of a specific step by referencing the step's instance.
+
+```typescript
+.then(step1)
+  .map(async ({ getStepResult }) => {
+    console.log(getStepResult(step1));
+  })
+```
+
+## Using `getInitData()`
+
+Use `getInitData<typeof workflow>()` to access the initial input data provided to the workflow.
+
+```typescript
+.then(step1)
+  .map(async ({ getInitData }) => {
+    console.log(getInitData<any>());
+  })
+```
+
+## Using `mapVariable()`
+
+The object form of `.map()` provides an alternative declarative syntax for mapping fields. Instead of writing a function, you define an object where each key is a new field name and each value uses `mapVariable()` to extract data from previous steps or workflow input. Import `mapVariable()` from the workflows module:
+
+```typescript
+import { mapVariable } from '@mastra/core/workflows'
+```
+
+### Extracting fields from step outputs
+
+Use `mapVariable()` with `step` to extract a specific field from a step's output and map it to a new field name. The `path` parameter specifies which field to extract. In this example, the `value` field from `step1`'s output is extracted and mapped to a new field called `details`:
+
+```typescript
+.then(step1)
+  .map({
+    details: mapVariable({
+      step: step1,
+      path: "value"
+    })
+  })
+```
+
+### Extracting fields from workflow input
+
+Use `mapVariable()` with `initData` to extract a specific field from the workflow's initial input data. This is useful when you need to pass the original workflow input to a later step. In this example, the `value` field from the workflow's input is extracted and mapped to a field called `details`:
+
+```typescript
+export const testWorkflow = createWorkflow({...});
+
+testWorkflow
+  .then(step1)
+  .map({
+    details: mapVariable({
+      initData: testWorkflow,
+      path: "value"
+    })
+  })
+```
+
+## Related
+
+- [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/reference-workflows-workflow-methods-parallel.md

@@ -0,0 +1,21 @@
+# Workflow\.parallel()
+
+The `.parallel()` method executes multiple steps in parallel.
+
+## Usage example
+
+```typescript
+workflow.parallel([step1, step2])
+```
+
+## Parameters
+
+**steps:** (`Step[]`): The step instances to execute in parallel
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Related
+
+- [Simultaneous steps with parallel](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/reference-workflows-workflow-methods-sleep.md

@@ -0,0 +1,35 @@
+# Workflow\.sleep()
+
+The `.sleep()` method pauses execution for a specified number of milliseconds. It accepts either a static number or a callback function for dynamic delays.
+
+## Usage example
+
+```typescript
+workflow.sleep(5000)
+```
+
+## Parameters
+
+**milliseconds:** (`number | ((context: { inputData: any }) => number | Promise<number>)`): The number of milliseconds to pause execution, or a callback that returns the delay
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Extended usage example
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleep(async ({ inputData }) => {
+    const { delayInMs } = inputData;
+    return delayInMs;
+  })
+  .then(step2)
+  .commit();
+```

package/dist/docs/references/reference-workflows-workflow-methods-sleepUntil.md

@@ -0,0 +1,35 @@
+# Workflow\.sleepUntil()
+
+The `.sleepUntil()` method pauses execution until a specified date.
+
+## Usage example
+
+```typescript
+workflow.sleepUntil(new Date(Date.now() + 5000))
+```
+
+## Parameters
+
+**dateOrCallback:** (`Date | ((params: ExecuteFunctionParams) => Promise<Date>)`): Either a Date object or a callback function that returns a Date. The callback receives execution context and can compute the target time dynamically based on input data.
+
+## Returns
+
+**workflow:** (`Workflow`): The workflow instance for method chaining
+
+## Extended usage example
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .sleepUntil(async ({ inputData }) => {
+    const { delayInMs } = inputData;
+    return new Date(Date.now() + delayInMs);
+  })
+  .then(step2)
+  .commit();
+```

package/dist/docs/references/reference-workflows-workflow-methods-then.md

@@ -0,0 +1,21 @@
+# Workflow\.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage example
+
+```typescript
+workflow.then(step1).then(step2)
+```
+
+## Parameters
+
+**step:** (`Step`): The step instance that should execute after the previous step completes
+
+## Returns
+
+**workflow:** (`NewWorkflow`): The workflow instance for method chaining
+
+## Related
+
+- [Control flow](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/reference-workflows-workflow.md

@@ -0,0 +1,157 @@
+# Workflow Class
+
+The `Workflow` class enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+
+## Usage example
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+export const workflow = createWorkflow({
+  id: 'test-workflow',
+  inputSchema: z.object({
+    value: z.string(),
+  }),
+  outputSchema: z.object({
+    value: z.string(),
+  }),
+})
+```
+
+## Constructor parameters
+
+**id:** (`string`): Unique identifier for the workflow
+
+**inputSchema:** (`z.ZodType<any>`): Zod schema defining the input structure for the workflow
+
+**outputSchema:** (`z.ZodType<any>`): Zod schema defining the output structure for the workflow
+
+**stateSchema?:** (`z.ZodObject<any>`): Optional Zod schema for the workflow state. Automatically injected when using Mastra's state system. If not specified, type is 'any'.
+
+**requestContextSchema?:** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of run.start(), throwing an error if validation fails.
+
+**options?:** (`WorkflowOptions`): Optional options for the workflow
+
+### WorkflowOptions
+
+**tracingPolicy?:** (`TracingPolicy`): Optional tracing policy for the workflow
+
+**validateInputs?:** (`boolean`): Optional flag to determine whether to validate the workflow inputs. This also applies default values from zodSchemas on the workflow/step input/resume data. If input/resume data validation fails on start/resume, the workflow will not start/resume, it throws an error instead. If input data validation fails on a step execution, the step fails, causing the workflow to fail and the error is returned. (Default: `true`)
+
+**shouldPersistSnapshot?:** (`(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean`): Optional flag to determine whether to persist the workflow snapshot (Default: `() => true`)
+
+**onFinish?:** (`(result: WorkflowFinishCallbackResult) => void | Promise<void>`): Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.
+
+**onError?:** (`(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>`): Callback invoked only when workflow fails (failed or tripwire status). Receives error details and step results. Errors thrown in this callback are caught and logged, not propagated.
+
+### WorkflowFinishCallbackResult
+
+The result object passed to `onFinish` callbacks.
+
+**status:** (`WorkflowRunStatus`): The workflow status: 'success', 'failed', 'suspended', or 'tripwire'
+
+**result?:** (`any`): The workflow output (when status is 'success')
+
+**error?:** (`SerializedError`): Error details (when status is 'failed')
+
+**steps:** (`Record<string, StepResult>`): Individual step results with their status and output
+
+**tripwire?:** (`StepTripwireInfo`): Tripwire information (when status is 'tripwire')
+
+**runId:** (`string`): The unique identifier for this workflow run
+
+**workflowId:** (`string`): The workflow's identifier
+
+**resourceId?:** (`string`): Optional resource identifier (if provided when creating the run)
+
+**getInitData:** (`() => any`): Function that returns the initial input data passed to the workflow
+
+**mastra?:** (`Mastra`): The Mastra instance (if workflow is registered with Mastra)
+
+**requestContext:** (`RequestContext`): Request-scoped context data
+
+**logger:** (`IMastraLogger`): The workflow's logger instance
+
+**state:** (`Record<string, any>`): The workflow's current state object
+
+### WorkflowErrorCallbackInfo
+
+The error info object passed to `onError` callbacks.
+
+**status:** (`'failed' | 'tripwire'`): The workflow status (either 'failed' or 'tripwire')
+
+**error?:** (`SerializedError`): Error details
+
+**steps:** (`Record<string, StepResult>`): Individual step results with their status and output
+
+**tripwire?:** (`StepTripwireInfo`): Tripwire information (when status is 'tripwire')
+
+**runId:** (`string`): The unique identifier for this workflow run
+
+**workflowId:** (`string`): The workflow's identifier
+
+**resourceId?:** (`string`): Optional resource identifier (if provided when creating the run)
+
+**getInitData:** (`() => any`): Function that returns the initial input data passed to the workflow
+
+**mastra?:** (`Mastra`): The Mastra instance (if workflow is registered with Mastra)
+
+**requestContext:** (`RequestContext`): Request-scoped context data
+
+**logger:** (`IMastraLogger`): The workflow's logger instance
+
+**state:** (`Record<string, any>`): The workflow's current state object
+
+## Running with initial state
+
+When starting a workflow run, you can pass `initialState` to set the starting values for the workflow's state:
+
+```typescript
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: { value: 'hello' },
+  initialState: {
+    counter: 0,
+    items: [],
+  },
+})
+```
+
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for more details.
+
+## Workflow status
+
+A workflow's `status` indicates its current execution state. The possible values are:
+
+**success:** (`string`): All steps finished executing successfully, with a valid result output
+
+**failed:** (`string`): Workflow encountered an error during execution, with error details available
+
+**suspended:** (`string`): Workflow execution is paused waiting for resume, with suspended step information
+
+**tripwire:** (`string`): Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.
+
+### Handling tripwire status
+
+When a workflow contains an agent step that triggers a tripwire, the workflow returns with `status: 'tripwire'` and includes tripwire details:
+
+```typescript
+const run = await workflow.createRun()
+const result = await run.start({ inputData: { message: 'Hello' } })
+
+if (result.status === 'tripwire') {
+  console.log('Workflow terminated by tripwire:', result.tripwire?.reason)
+  console.log('Processor ID:', result.tripwire?.processorId)
+  console.log('Retry requested:', result.tripwire?.retry)
+}
+```
+
+This is distinct from `status: 'failed'` which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).
+
+## Related
+
+- [Step Class](https://mastra.ai/reference/workflows/step)
+- [Workflow State](https://mastra.ai/docs/workflows/workflow-state)
+- [Control flow](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/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)