Unclaimed project
Are you a maintainer of mastra? Claim this project to take control of your public changelog and roadmap.
Changelog
From the team behind Gatsby, Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
Last updated about 22 hours ago
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞
Interactive roadmaps, guides and other educational content to help developers grow in their careers.
This is the repo for Vue 2. For Vue 3, go to https://github.com/vuejs/core
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fixed agent network not returning text response when routing agent handles requests without delegation. (#11497)
What changed:
Why this matters:
Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.
Fixes #11219
Refactor the MessageList class from ~4000 LOC monolith to ~850 LOC with focused, single-responsibility modules. This improves maintainability, testability, and makes the codebase easier to understand. (#11658)
message-list/
├── message-list.ts # Main class (~850 LOC, down from ~4000)
├── adapters/ # SDK format conversions
│ ├── AIV4Adapter.ts # MastraDBMessage <-> AI SDK V4
│ └── AIV5Adapter.ts # MastraDBMessage <-> AI SDK V5
├── cache/
│ └── CacheKeyGenerator.ts # Deduplication keys
├── conversion/
│ ├── input-converter.ts # Any format -> MastraDBMessage
│ ├── output-converter.ts # MastraDBMessage -> SDK formats
│ ├── step-content.ts # Step content extraction
│ └── to-prompt.ts # LLM prompt formatting
├── detection/
│ └── TypeDetector.ts # Format identification
├── merge/
│ └── MessageMerger.ts # Streaming merge logic
├── state/
│ └── MessageStateManager.ts # Source & persistence tracking
└── utils/
└── provider-compat.ts # Provider-specific fixes
Fix autoresume not working fine in useChat (#11486)
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Improves AI SDK message conversion for Braintrust Thread view: (#11673)
result and v5 output fields for tool resultsAdd embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)
+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });
Add initial state input to workflow form in studio (#11560)
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneMake agentId optional for memory read operations (getThread, listThreads, listMessages) (#11540)
When workflows use multiple agents sharing the same threadId/resourceId, users can now retrieve threads and messages without specifying an agentId. The server falls back to using storage directly when agentId is not provided.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Breaking Change: memory.readOnly has been moved to memory.options.readOnly (#11523)
The readOnly option now lives inside memory.options alongside other memory configuration like lastMessages and semanticRecall.
Before:
agent.stream('Hello', {
memory: {
thread: threadId,
resource: resourceId,
readOnly: true,
},
});
After:
agent.stream('Hello', {
memory: {
thread: threadId,
resource: resourceId,
options: {
readOnly: true,
},
},
});
Migration: Run the codemod to update your code automatically:
npx @mastra/codemod@beta v1/memory-readonly-to-options .
This also fixes issue #11519 where readOnly: true was being ignored and messages were saved to memory anyway.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Deprecate default: { enabled: true } observability configuration (#11674)
The shorthand default: { enabled: true } configuration is now deprecated and will be removed in a future version. Users should migrate to explicit configuration with DefaultExporter, CloudExporter, and SensitiveDataFilter.
Before (deprecated):
import { Observability } from '@mastra/observability';
const mastra = new Mastra({
observability: new Observability({
default: { enabled: true },
}),
});
After (recommended):
import { Observability, DefaultExporter, CloudExporter, SensitiveDataFilter } from '@mastra/observability';
const mastra = new Mastra({
observability: new Observability({
configs: {
default: {
serviceName: 'mastra',
exporters: [new DefaultExporter(), new CloudExporter()],
spanOutputProcessors: [new SensitiveDataFilter()],
},
},
}),
});
The explicit configuration makes it clear exactly what exporters and processors are being used, improving code readability and maintainability.
A deprecation warning will be logged when using the old configuration pattern.
Fix processor tracing to create individual spans per processor (#11683)
input processor: validator) instead of combined workflow IDsINPUT_STEP_PROCESSOR and OUTPUT_STEP_PROCESSOR entity types for finer-grained tracingprocessorType span attribute to processorExecutor with values 'workflow' or 'legacy'Add completion validation to agent networks using custom scorers (#11562)
You can now validate whether an agent network has completed its task by passing MastraScorers to agent.network(). When validation fails, the network automatically retries with feedback injected into the conversation.
Example: Creating a scorer to verify test coverage
import { createScorer } from '@mastra/core/evals';
import { z } from 'zod';
// Create a scorer that checks if tests were written
const testsScorer = createScorer({
id: 'tests-written',
description: 'Validates that unit tests were included in the response',
type: 'agent',
}).generateScore({
description: 'Return 1 if tests are present, 0 if missing',
outputSchema: z.number(),
createPrompt: ({ run }) => `
Does this response include unit tests?
Response: ${run.output}
Return 1 if tests are present, 0 if not.
`,
});
// Use the scorer with agent.network()
const stream = await agent.network('Implement a fibonacci function with tests', {
completion: {
scorers: [testsScorer],
strategy: 'all', // all scorers must pass (score >= 0.5)
},
maxSteps: 3,
});
What this enables:
score: 0, its reason is injected into the conversation so the network can address the gap on the next iterationstrategy: 'all' (all must pass) or strategy: 'any' (at least one must pass)This replaces guesswork with reliable, repeatable validation that ensures agent networks produce outputs meeting your specific requirements.
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add support for retries and scorers parameters across all createStep overloads.
(#11495)
The createStep function now includes support for the retries and scorers fields across all step creation patterns, enabling step-level retry configuration and AI evaluation support for regular steps, agent-based steps, and tool-based steps.
import { init } from '@mastra/inngest';
import { z } from 'zod';
const { createStep } = init(inngest);
// 1. Regular step with retries
const regularStep = createStep({
id: 'api-call',
inputSchema: z.object({ url: z.string() }),
outputSchema: z.object({ data: z.any() }),
retries: 3, // ← Will retry up to 3 times on failure
execute: async ({ inputData }) => {
const response = await fetch(inputData.url);
return { data: await response.json() };
},
});
// 2. Agent step with retries and scorers
const agentStep = createStep(myAgent, {
retries: 3,
scorers: [{ id: 'accuracy-scorer', scorer: myAccuracyScorer }],
});
// 3. Tool step with retries and scorers
const toolStep = createStep(myTool, {
retries: 2,
scorers: [{ id: 'quality-scorer', scorer: myQualityScorer }],
});
This change ensures API consistency across all createStep overloads. All step types now support retry and evaluation configurations.
This is a non-breaking change - steps without these parameters continue to work exactly as before.
Fixes #9351
Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)
+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });
Fix workflow tool not executing when requireApproval is true and tool call is approved (#11538)
Breaking Change: memory.readOnly has been moved to memory.options.readOnly (#11523)
The readOnly option now lives inside memory.options alongside other memory configuration like lastMessages and semanticRecall.
Before:
agent.stream('Hello', {
memory: {
thread: threadId,
resource: resourceId,
readOnly: true,
},
});
After:
agent.stream('Hello', {
memory: {
thread: threadId,
resource: resourceId,
options: {
readOnly: true,
},
},
});
Migration: Run the codemod to update your code automatically:
npx @mastra/codemod@beta v1/memory-readonly-to-options .
This also fixes issue #11519 where readOnly: true was being ignored and messages were saved to memory anyway.
Fix agent runs with multiple steps only showing last text chunk in observability tools (#11672)
When an agent model executes multiple steps and generates multiple text chunks, the onFinish payload was only receiving the text from the last step instead of all accumulated text. This caused observability tools like Braintrust to only display the final text chunk. The fix now correctly concatenates all text chunks from all steps.
Fix tool input validation destroying non-plain objects (#11541)
The convertUndefinedToNull function in tool input validation was treating all objects as plain objects and recursively processing them. For objects like Date, Map, URL, and class instances, this resulted in empty objects {} because they have no enumerable own properties.
This fix changes the approach to only recurse into plain objects (objects with Object.prototype or null prototype). All other objects (Date, Map, Set, URL, RegExp, Error, custom class instances, etc.) are now preserved as-is.
Fixes #11502
Fixed client-side tool invocations not being stored in memory. Previously, tool invocations with state 'call' were filtered out before persistence, which incorrectly removed client-side tools. Now only streaming intermediate states ('partial-call') are filtered. (#11630)
Fixed a crash when updating working memory with an empty or null update; existing data is now preserved.
Fixed memory readOnly option not being respected when agents share a RequestContext. Previously, when output processors were resolved, the readOnly check happened too early - before the agent could set its own MastraMemory context. This caused child agents to inherit their parent's readOnly setting when sharing a RequestContext. (#11653)
The readOnly check is now only done at execution time in each processor's processOutputResult method, allowing proper isolation.
Fix network validation not seeing previous iteration results in multi-step tasks (#11691)
The validation LLM was unable to determine task completion for multi-step tasks because it couldn't see what primitives had already executed. Now includes a compact list of completed primitives in the validation prompt.
Fix provider-executed tools (like openai.tools.webSearch()) not working correctly with AI SDK v6 models. The agent's generate() method was ending prematurely with finishReason: 'tool-calls' instead of completing with a text response after tool execution. (#11622)
The issue was that V6 provider tools have type: 'provider' while V5 uses type: 'provider-defined'. The tool preparation code now detects the model version and uses the correct type.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
fix(core): support LanguageModelV3 in MastraModelGateway.resolveLanguageModel (#11489)
Fixed agent network not returning text response when routing agent handles requests without delegation. (#11497)
What changed:
Why this matters:
Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.
Fixes #11219
Add initial state input to workflow form in studio (#11560)
Added missing stream types to @mastra/core/stream for better TypeScript support (#11513)
New types available:
ToolCallChunk, ToolResultChunk, SourceChunk, FileChunk, ReasoningChunkToolCallPayload, ToolResultPayload, TextDeltaPayload, ReasoningDeltaPayload, FilePayload, SourcePayloadJSONValue, JSONObject, JSONArray and readonly variantsThese types are now properly exported, enabling full TypeScript IntelliSense when working with streaming data.
Refactor the MessageList class from ~4000 LOC monolith to ~850 LOC with focused, single-responsibility modules. This improves maintainability, testability, and makes the codebase easier to understand. (#11658)
message-list/
├── message-list.ts # Main class (~850 LOC, down from ~4000)
├── adapters/ # SDK format conversions
│ ├── AIV4Adapter.ts # MastraDBMessage <-> AI SDK V4
│ └── AIV5Adapter.ts # MastraDBMessage <-> AI SDK V5
├── cache/
│ └── CacheKeyGenerator.ts # Deduplication keys
├── conversion/
│ ├── input-converter.ts # Any format -> MastraDBMessage
│ ├── output-converter.ts # MastraDBMessage -> SDK formats
│ ├── step-content.ts # Step content extraction
│ └── to-prompt.ts # LLM prompt formatting
├── detection/
│ └── TypeDetector.ts # Format identification
├── merge/
│ └── MessageMerger.ts # Streaming merge logic
├── state/
│ └── MessageStateManager.ts # Source & persistence tracking
└── utils/
└── provider-compat.ts # Provider-specific fixes
Resolve suspendPayload when tripwire is set off in agentic loop to prevent unresolved promises hanging. (#11621)
Fix OpenAI reasoning model + memory failing on second generate with "missing item" error (#11492)
When using OpenAI reasoning models with memory enabled, the second agent.generate() call would fail with: "Item 'rs_...' of type 'reasoning' was provided without its required following item."
The issue was that text-start events contain providerMetadata with the text's itemId (e.g., msg_xxx), but this metadata was not being captured. When memory replayed the conversation, the reasoning part had its rs_ ID but the text part was missing its msg_ ID, causing OpenAI to reject the request.
The fix adds handlers for text-start (to capture text providerMetadata) and text-end (to clear it and prevent leaking into subsequent parts).
Fixes #11481
Fix reasoning content being lost when text-start chunk arrives before reasoning-end (#11494)
Some model providers (e.g., ZAI/glm-4.6) return streaming chunks where text-start arrives before reasoning-end. Previously, this would clear the accumulated reasoning deltas, resulting in empty reasoning content in the final message. Now text-start is properly excluded from triggering the reasoning state reset, allowing reasoning-end to correctly save the reasoning content.
Add resumeGenerate method for resuming agent via generate (#11503)
Add runId and suspendPayload to fullOutput of agent stream
Default suspendedToolRunId to empty string to prevent null issue
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneFix runEvals() to automatically save scores to storage, making them visible in Studio observability. (#11516)
Previously, runEvals() would calculate scores but not persist them to storage, requiring users to manually implement score saving via the onItemComplete callback. Scores now automatically save when the target (Agent/Workflow) has an associated Mastra instance with storage configured.
What changed:
getMastraInstance()) and Workflow (.mastra getter)groundTruth (in additionalContext), requestContext, traceId, and spanIdsource: 'TEST' to distinguish them from live scoringMigration:
No action required. The onItemComplete workaround for saving scores can be removed if desired, but will continue to work for custom logic.
Example:
const result = await runEvals({
target: mastra.getWorkflow("myWorkflow"),
data: [{ input: {...}, groundTruth: {...} }],
scorers: [myScorer],
});
// Scores are now automatically saved and visible in Studio!
Fix autoresume not working fine in useChat (#11486)
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fixed module resolution failing on Windows with ERR_INVALID_URL_SCHEME errors. Windows absolute paths (e.g., C:\path\to\file) are now correctly skipped during node_modules resolution instead of being treated as package names. (#11639)
Add Bun runtime detection for bundler platform selection (#11548)
When running under Bun, the bundler now uses neutral esbuild platform instead of node to preserve Bun-specific globals (like Bun.s3). This fixes compatibility issues where Bun APIs were being incorrectly transformed during the build process.
Improved file persistence in dev mode. Files created by mastra dev are now saved in the public directory, so you can commit them to version control or ignore them via .gitignore. (#11234)
Fixed Windows crash where the Mastra dev server failed to start with ERR_UNSUPPORTED_ESM_URL_SCHEME error. The deployer now correctly handles Windows file paths. (#11340)
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Users no longer need to install the ai package as a peer dependency; this package now includes the necessary types internally. (#11625)
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fixed inconsistent query parameter handling across server adapters. (#11429)
What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.
Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.
User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
feat: Add Fastify and Koa server adapters (#11568)
Introduces two new server adapters for Mastra:
Both adapters provide full MastraServerBase implementation including route registration, streaming responses, multipart uploads, auth middleware, and MCP transport support.
import Fastify from 'fastify';
import { MastraServer } from '@mastra/fastify';
import { mastra } from './mastra';
const app = Fastify();
const server = new MastraServer({ app, mastra });
await server.init();
app.listen({ port: 4111 });
import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { MastraServer } from '@mastra/koa';
import { mastra } from './mastra';
const app = new Koa();
app.use(bodyParser());
const server = new MastraServer({ app, mastra });
await server.init();
app.listen(4111);
Fixed inconsistent query parameter handling across server adapters. (#11429)
What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.
Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.
User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fixed inconsistent query parameter handling across server adapters. (#11429)
What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.
Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.
User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.
Add support for retries and scorers parameters across all createStep overloads.
(#11495)
The createStep function now includes support for the retries and scorers fields across all step creation patterns, enabling step-level retry configuration and AI evaluation support for regular steps, agent-based steps, and tool-based steps.
import { init } from '@mastra/inngest';
import { z } from 'zod';
const { createStep } = init(inngest);
// 1. Regular step with retries
const regularStep = createStep({
id: 'api-call',
inputSchema: z.object({ url: z.string() }),
outputSchema: z.object({ data: z.any() }),
retries: 3, // ← Will retry up to 3 times on failure
execute: async ({ inputData }) => {
const response = await fetch(inputData.url);
return { data: await response.json() };
},
});
// 2. Agent step with retries and scorers
const agentStep = createStep(myAgent, {
retries: 3,
scorers: [{ id: 'accuracy-scorer', scorer: myAccuracyScorer }],
});
// 3. Tool step with retries and scorers
const toolStep = createStep(myTool, {
retries: 2,
scorers: [{ id: 'quality-scorer', scorer: myQualityScorer }],
});
This change ensures API consistency across all createStep overloads. All step types now support retry and evaluation configurations.
This is a non-breaking change - steps without these parameters continue to work exactly as before.
Fixes #9351
Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)
+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add cron scheduling support to Inngest workflows. Workflows can now be automatically triggered on a schedule by adding a cron property along with optional inputData and initialState: (#11518)
const workflow = createWorkflow({
id: 'scheduled-workflow',
inputSchema: z.object({ value: z.string() }),
outputSchema: z.object({ result: z.string() }),
steps: [step1],
cron: '0 0 * * *', // Run daily at midnight
inputData: { value: 'scheduled-run' }, // Optional inputData for the scheduled workflow run
initialState: { count: 0 }, // Optional initialState for the scheduled workflow run
});
feat: Add Fastify and Koa server adapters (#11568)
Introduces two new server adapters for Mastra:
Both adapters provide full MastraServerBase implementation including route registration, streaming responses, multipart uploads, auth middleware, and MCP transport support.
import Fastify from 'fastify';
import { MastraServer } from '@mastra/fastify';
import { mastra } from './mastra';
const app = Fastify();
const server = new MastraServer({ app, mastra });
await server.init();
app.listen({ port: 4111 });
import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { MastraServer } from '@mastra/koa';
import { mastra } from './mastra';
const app = new Koa();
app.use(bodyParser());
const server = new MastraServer({ app, mastra });
await server.init();
app.listen(4111);
Fixed inconsistent query parameter handling across server adapters. (#11429)
What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.
Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.
User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneAdd embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fixed client-side tool invocations not being stored in memory. Previously, tool invocations with state 'call' were filtered out before persistence, which incorrectly removed client-side tools. Now only streaming intermediate states ('partial-call') are filtered. (#11630)
Fixed a crash when updating working memory with an empty or null update; existing data is now preserved.
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneUnified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Deprecate default: { enabled: true } observability configuration (#11674)
The shorthand default: { enabled: true } configuration is now deprecated and will be removed in a future version. Users should migrate to explicit configuration with DefaultExporter, CloudExporter, and SensitiveDataFilter.
Before (deprecated):
import { Observability } from '@mastra/observability';
const mastra = new Mastra({
observability: new Observability({
default: { enabled: true },
}),
});
After (recommended):
import { Observability, DefaultExporter, CloudExporter, SensitiveDataFilter } from '@mastra/observability';
const mastra = new Mastra({
observability: new Observability({
configs: {
default: {
serviceName: 'mastra',
exporters: [new DefaultExporter(), new CloudExporter()],
spanOutputProcessors: [new SensitiveDataFilter()],
},
},
}),
});
The explicit configuration makes it clear exactly what exporters and processors are being used, improving code readability and maintainability.
A deprecation warning will be logged when using the old configuration pattern.
Fix processor tracing to create individual spans per processor (#11683)
input processor: validator) instead of combined workflow IDsINPUT_STEP_PROCESSOR and OUTPUT_STEP_PROCESSOR entity types for finer-grained tracingprocessorType span attribute to processorExecutor with values 'workflow' or 'legacy'Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fix trace-level sampling to sample entire traces instead of individual spans (#11676)
Previously, sampling decisions were made independently for each span, causing fragmented traces where some spans were sampled and others were not. This defeated the purpose of ratio or custom sampling strategies.
Now:
Fixes #11504
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)
What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.
Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
Example:
// Get first page
const page1 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
});
// Get next page using cursor-based pagination
const oldestMessage = page1.messages[page1.messages.length - 1];
const page2 = await memory.recall({
threadId: 'thread-123',
perPage: 10,
orderBy: { field: 'createdAt', direction: 'DESC' },
filter: {
dateRange: {
end: oldestMessage.createdAt,
endExclusive: true, // Excludes the cursor message
},
},
});
Fix thread timestamps being returned in incorrect timezone from listThreadsByResourceId (#11498)
The method was not using the timezone-aware columns (createdAtZ/updatedAtZ), causing timestamps to be interpreted in local timezone instead of UTC. Now correctly uses TIMESTAMPTZ columns with fallback for legacy data.
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneAdd embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add missing loading state handlers to TanStack Query hooks. Components now properly show skeleton/loading UI instead of returning null or rendering incomplete states while data is being fetched. (#11681)
Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)
+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });
Dedupe Avatar component by removing UI avatar and using DS Avatar with size variants (#11637)
Consolidate date picker components by removing duplicate DatePicker and Calendar components. DateField now uses the DayPicker wrapper from date-time-picker folder directly. (#11649)
Consolidate tabs components: remove redundant implementations and add onClose prop support (#11650)
Use the same Button component every where. Remove duplicates. (#11635)
Add initial state input to workflow form in studio (#11560)
Remove unused files and dependencies identified by Knip (#11677)
Fix react/react-DOM version mismatch. (#11620)
Adds thread cloning to create independent copies of conversations that can diverge. (#11517)
// Clone a thread
const { thread, clonedMessages } = await memory.cloneThread({
sourceThreadId: 'thread-123',
title: 'My Clone',
options: {
messageLimit: 10, // optional: only copy last N messages
},
});
// Check if a thread is a clone
if (memory.isClone(thread)) {
const source = await memory.getSourceThread(thread.id);
}
// List all clones of a thread
const clones = await memory.listClones('thread-123');
Includes:
POST /api/memory/threads/:threadId/cloneDisplay network completion validation results and scorer feedback in the Playground when viewing agent network runs, letting users see pass/fail status and actionable feedback from completion scorers (#11562)
Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)
What changed:
getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)fields parameter to request only specific fields for better performancewithNestedWorkflows parameter to control nested workflow step inclusiongetWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)/execution-result API endpoints from server (breaking change)runExecutionResult() method from client SDK (breaking change)GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)Before:
// Had to call two different methods for different data
const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state
After:
// Single method returns everything
const run = await workflow.getWorkflowRunById(runId);
// Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
// Request only specific fields for better performance (avoids expensive step fetching)
const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
// Skip nested workflow steps for faster response
const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });
Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Add dynamic vectorStore resolver support for multi-tenant applications (#11542)
The vectorStore option in createVectorQueryTool and createGraphRAGTool now accepts a resolver function in addition to static instances. This enables multi-tenant setups where each tenant has isolated data in separate PostgreSQL schemas.
Also improves providerOptions type safety by using MastraEmbeddingOptions types instead of a generic Record type.
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Fix TypeScript errors during build declaration generation (#11682)
Updated test file toUIMessage.test.ts to match current @mastra/core types:
error property from string to Error object (per StepFailure type)resumeSchema property to tool-call-approval payloads (per ToolCallApprovalPayload type)zod as peer/dev dependency for test type supportFixed agent network not returning text response when routing agent handles requests without delegation. (#11497)
What changed:
Why this matters:
Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.
Fixes #11219
Display network completion validation results and scorer feedback in the Playground when viewing agent network runs, letting users see pass/fail status and actionable feedback from completion scorers (#11562)
Add embedded documentation support for Mastra packages (#11472)
Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.
Each package includes:
Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
Note: Release notes were truncated due to GitHub's 125,000 character limit. See the full changelog details at the link below.
Full Changelog: b3e7a74