@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-streaming-workflows-resumeStream.md

@@ -0,0 +1,61 @@
+# Run.resumeStream()
+
+The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+const result = await stream.result
+
+if (result!.status === 'suspended') {
+  const resumedStream = await run.resumeStream({
+    resumeData: {
+      value: 'resume data',
+    },
+  })
+}
+```
+
+## Parameters
+
+**resumeData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+
+**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+
+**step?:** (`Step<string, any, any, any, any, TEngineType>`): The step to resume execution from
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+## Returns
+
+**stream:** (`MastraWorkflowStream<ChunkType>`): A custom stream that extends ReadableStream\<ChunkType> with additional workflow-specific properties
+
+**stream.status:** (`Promise<RunStatus>`): A promise that resolves to the current workflow run status
+
+**stream.result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+
+**stream.usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>`): A promise that resolves to token usage statistics
+
+## Stream Events
+
+The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
+- [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream)

package/dist/docs/references/reference-streaming-workflows-stream.md

@@ -0,0 +1,88 @@
+# Run.stream()
+
+The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+## Parameters
+
+**inputData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
+
+**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**closeOnSuspend?:** (`boolean`): Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.
+
+## Returns
+
+Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
+
+**fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.
+
+**result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+
+**status:** (`WorkflowRunStatus`): The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')
+
+**usage:** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>`): A promise that resolves to token usage statistics
+
+## Extended usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const stream = run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+
+// Access the final result
+const result = await stream.result
+console.log('Final result:', result)
+
+// Access token usage
+const usage = await stream.usage
+console.log('Token usage:', usage)
+
+// Check current status
+console.log('Status:', stream.status)
+```
+
+## Stream Events
+
+The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
+
+- **`workflow-start`**: Workflow execution begins
+- **`workflow-step-start`**: A step begins execution
+- **`workflow-step-output`**: Custom output from a step
+- **`workflow-step-progress`**: A foreach step reports per-iteration progress (includes `completedCount`, `totalCount`, `currentIndex`, `iterationStatus`, and optional `iterationOutput`)
+- **`workflow-step-result`**: A step completes with results
+- **`workflow-finish`**: Workflow execution completes with usage statistics
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)
+- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
+- [Run.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)

package/dist/docs/references/reference-streaming-workflows-timeTravelStream.md

@@ -0,0 +1,142 @@
+# Run.timeTravelStream()
+
+The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
+
+## Usage example
+
+```typescript
+const run = await workflow.createRun()
+
+const output = run.timeTravelStream({
+  step: 'step2',
+  inputData: { value: 10 },
+})
+
+// Process events as they arrive
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload)
+}
+
+// Get the final result
+const result = await output.result
+```
+
+## Parameters
+
+All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/workflows/run-methods/timeTravel). See the [timeTravel reference](https://mastra.ai/reference/workflows/run-methods/timeTravel) for detailed parameter documentation.
+
+## Returns
+
+**output:** (`WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>`): An object containing both the stream and result promise
+
+**output.fullStream:** (`ReadableStream<WorkflowStreamEvent>`): A readable stream that emits workflow events as execution progresses
+
+**output.result:** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
+
+**output.traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled
+
+## Stream events
+
+The stream emits various workflow events during execution:
+
+- `workflow-step-start`: Emitted when a step begins execution
+- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-error`: Emitted when a step encounters an error
+- `workflow-step-suspended`: Emitted when a step suspends
+- Additional events depending on step types (agents, tools, etc.)
+
+## Extended usage examples
+
+### Processing events during time travel
+
+```typescript
+const run = await workflow.createRun()
+
+const output = run.timeTravelStream({
+  step: 'step2',
+  inputData: { value: 10 },
+})
+
+for await (const event of output.fullStream) {
+  switch (event.type) {
+    case 'workflow-step-start':
+      console.log(`Starting step: ${event.payload.stepName}`)
+      break
+    case 'workflow-step-finish':
+      console.log(`Completed step: ${event.payload.stepName}`)
+      break
+    case 'workflow-step-error':
+      console.error(`Error in step: ${event.payload.stepName}`, event.payload.error)
+      break
+  }
+}
+
+const result = await output.result
+console.log('Time travel completed:', result)
+```
+
+### Time travel stream with context
+
+```typescript
+const output = run.timeTravelStream({
+  step: 'step2',
+  context: {
+    step1: {
+      status: 'success',
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+  },
+})
+
+for await (const event of output.fullStream) {
+  // Handle events
+  console.log(event)
+}
+
+const result = await output.result
+```
+
+### Time travel stream with nested workflows
+
+```typescript
+const output = run.timeTravelStream({
+  step: ['nestedWorkflow', 'step3'],
+  inputData: { value: 10 },
+  nestedStepsContext: {
+    nestedWorkflow: {
+      step2: {
+        status: 'success',
+        payload: { step1Result: 2 },
+        output: { step2Result: 3 },
+        startedAt: Date.now(),
+        endedAt: Date.now(),
+      },
+    },
+  },
+})
+
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload)
+}
+
+const result = await output.result
+```
+
+## Notes
+
+- The stream closes automatically when time travel execution completes or encounters an error
+- You can process events from the stream while the workflow is still executing
+- The `result` promise resolves only after all steps have completed
+- Stream events follow the same format as regular workflow streaming
+- Time travel streaming requires storage to be configured since it relies on persisted workflow snapshots
+
+## Related
+
+- [Run.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming)
+- [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream)
+- [Run.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)

package/dist/docs/references/reference-templates-overview.md

@@ -0,0 +1,194 @@
+# Overview
+
+This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.
+
+Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:
+
+- **Working examples** - Complete, functional Mastra applications
+- **Best practices** - Proper project structure and coding conventions
+- **Educational resources** - Learn Mastra patterns through real implementations
+- **Quick starts** - Bootstrap projects faster than building from scratch
+
+## Using Templates
+
+### Installation
+
+Install a template using the `create-mastra` command:
+
+```bash
+npx create-mastra@latest --template template-name
+```
+
+This creates a complete project with all necessary code and configuration.
+
+### Setup Process
+
+After installation:
+
+1. **Navigate to project directory**:
+
+   ```bash
+   cd your-project-name
+   ```
+
+2. **Configure environment variables**:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` with required API keys as documented in the template's README.
+
+3. **Install dependencies** (if not done automatically):
+
+   ```bash
+   npm install
+   ```
+
+4. **Start development server**:
+
+   ```bash
+   npm run dev
+   ```
+
+### Template Structure
+
+All templates follow this standardized structure:
+
+## Creating Templates
+
+### Requirements
+
+Templates must meet these technical requirements:
+
+#### Project Structure
+
+- **Mastra code location**: All Mastra code must be in `src/mastra/` directory
+
+- **Component organization**:
+
+  - Agents: `src/mastra/agents/`
+  - Tools: `src/mastra/tools/`
+  - Workflows: `src/mastra/workflows/`
+  - Main config: `src/mastra/index.ts`
+
+#### TypeScript Configuration
+
+Use the standard Mastra TypeScript configuration:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+#### Environment Configuration
+
+Include a `.env.example` file with all required environment variables:
+
+```bash
+# LLM provider API keys (choose one or more)
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
+
+# Other service API keys as needed
+OTHER_SERVICE_API_KEY=your_api_key_here
+```
+
+### Code Standards
+
+#### LLM Provider
+
+We recommend using OpenAI, Anthropic, or Google model providers for templates. Choose the provider that best fits your use case:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const agent = new Agent({
+  name: 'example-agent',
+  model: 'openai/gpt-5.1', // or other provider strings
+  instructions: 'Your agent instructions here',
+})
+```
+
+#### Compatibility Requirements
+
+Templates must be:
+
+- **Single projects** - Not monorepos with multiple applications
+- **Framework-free** - No Next.js, Express, or other web framework boilerplate
+- **Mastra-focused** - Demonstrate Mastra functionality without additional layers
+- **Mergeable** - Structure code for easy integration into existing projects
+- **Node.js compatible** - Support Node.js v22.13.0 and later
+- **ESM modules** - Use ES modules (`"type": "module"` in package.json)
+
+### Documentation Requirements
+
+#### README Structure
+
+Every template must include a comprehensive README:
+
+```markdown
+# Template Name
+
+Brief description of what the template demonstrates.
+
+## Overview
+
+Detailed explanation of the template's functionality and use case.
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your API keys
+2. Install dependencies: `npm install`
+3. Run the project: `npm run dev`
+
+## Environment Variables
+
+- `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
+- `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
+- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
+- `OTHER_API_KEY`: Description of what this key is for
+
+## Usage
+
+Instructions on how to use the template and examples of expected behavior.
+
+## Customization
+
+Guidelines for modifying the template for different use cases.
+```
+
+#### Code Comments
+
+Include clear comments explaining:
+
+- Complex logic or algorithms
+- API integrations and their purpose
+- Configuration options and their effects
+- Example usage patterns
+
+### Quality Standards
+
+Templates must demonstrate:
+
+- **Code quality** - Clean, well-commented, maintainable code
+- **Error handling** - Proper handling for external APIs and user inputs
+- **Type safety** - Full TypeScript typing with Zod validation
+- **Testing** - Verified functionality with fresh installations
+
+For information on contributing your own templates to the Mastra ecosystem, see the [Contributing Templates](https://mastra.ai/docs/community/contributing-templates) guide in the community section.
+
+> **Info:** Templates provide an excellent way to learn Mastra patterns and accelerate development. Contributing templates helps the entire community build better AI applications.