@mastra/core 1.6.0 → 1.7.0-alpha.0

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

@@ -1,61 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,142 +0,0 @@
-# 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

@@ -1,194 +0,0 @@
-# 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.