Mastra release notes, breaking changes, and upgrade notes.
TypeScript agent framework with workflows, RAG, and evals StackPulse turns upstream changelogs into scannable summaries with risky changes, deprecations, migration notes, and source links.
This release introduces significant observability enhancements, including capabilities negotiation and discovery-backed filters, alongside new features like eager tool execution and Discord integration. It also includes a breaking change in the `TaskList` API and a security fix for dataset schema validation.
affected
Developers using `@mastra/playground-ui` `TaskList` API or custom observability stores are affected by breaking changes and new feature integrations.
action
Update to leverage new observability features and review breaking changes in `@mastra/playground-ui`.
release_signals
-`@mastra/playground-ui` `TaskList` API: `title`, `TaskListHeader`, and `hideWhenEmpty` are removed.
!Fixed a denial-of-service risk in dataset schema validation by using a linear-time (RE2) engine for regex patterns.
+Observability Capabilities Negotiation for detecting supported APIs.
This release introduces dynamic model routing, cross-process cancellation, and enhanced trace querying. It also includes breaking changes for UI components in `@mastra/playground-ui`.
affected
Users of `@mastra/playground-ui` are affected by breaking changes in UI components.
action
Review breaking changes in `@mastra/playground-ui` and update components accordingly.
-`@mastra/playground-ui`: `PermissionDenied` and `SessionExpired` moved to auth domain with simplified props (custom copy/actions require rendering `EmptyState` directly).
This release introduces classifiers as a first-class primitive, enabling typed workflow steps and policy enforcement. It also adds native background tool execution and expands SaaS tool integrations via `@mastra/connect`.
affected
Developers using classifiers, SaaS integrations, or background tool execution will benefit from these updates.
action
Review breaking changes and migrate deprecated APIs to their replacements.
release_signals
-`@mastra/playground-ui`: Removed `@mastra/playground-ui/lib/springs`; `FluidHoverHighlight` API simplified.
-`@mastra/playground-ui`: Reworked `PageLayout`/shell APIs; removed `PageLayoutRoot`, `MainContentLayout`, and others.
This release introduces significant updates including new vector stores (Azure AI Search + Weaviate), improved observability trace querying with pagination, and performance optimizations for durable agents. It also includes breaking changes in the MCP protocol and agent controller message events.
affected
Users of `@mastra/mcp` and agent controllers are affected by breaking changes in message events and MCP protocol.
action
Review the MCP v2 migration guide for breaking changes in `@mastra/mcp@2.0.0` and update agent controller implementations to handle new message event formats.
release_signals
-Agent Controller stream message events changed: one full `message_start`, then ID-addressed `message_update` deltas; `message_end` now contains only the message ID (store by ID and apply updates).
This release introduces the Studio Workflow Builder backend, a new `@mastra/connect` package for platform integrations, thread ownership transfer capabilities, enhanced background tool execution controls, and improved workspace and sandbox functionalities.
affected
Developers using Mastra's workflow builder, platform integrations, thread management, and background tool execution will be affected.
action
Review the breaking changes and update your code accordingly.
release_signals
-Replaced `subscribeQueuedMessages` with `subscribeThreadEvents`.
-Renamed `ArchilFilesystem.grep()` to `diskGrep()`.
+Studio Workflow Builder backend for persisted workflow definitions.
@mastra/core@1.66.0highfeatureSep 11, 2026
September 10, 2026
This release introduces advanced trace querying capabilities, observability signal deletion, and streaming reliability improvements. It also adds deploy-scoped worker provisioning and observational memory transform hooks.
affected
Developers using Mastra for observability, trace querying, and model streaming will benefit from new features and reliability improvements.
action
Review the new trace query capabilities and observability deletion methods to enhance your monitoring workflows.
release_signals
+Deploy-scoped worker provisioning for Mastra Cloud with `workers.json` manifest
+Advanced trace queries with richer filtering across span fields, metadata, feedback, and scores
+Observability signal deletion (feedback + scores) across storage, server, and client
@mastra/core@1.65.0highbreakingfeatureSep 9, 2026
September 9, 2026
This release introduces advanced trace querying and tenant-scoped trace deletion, along with workflow graph metadata and agent channel actions. It also includes breaking changes for `@mastra/factory` and `@mastra/playground-ui`.
affected
Developers using `@mastra/factory` and `@mastra/playground-ui` are affected by breaking changes, while those using advanced trace querying or tenant-scoped trace deletion will benefit from new features.
action
Review breaking changes for `@mastra/factory` and `@mastra/playground-ui` and update your code accordingly.
release_signals
-`@mastra/factory`: `defineBoard()` phases must add `kind`, working phases must add `role`, and `initialPhase` must be `resting`.
This release introduces reusable sandbox templates with warm repo checkouts, a unified `workingDirectory` option across sandbox providers, and server-defined `toModelOutput` for client-side tools. It also adds a feedback review workflow and a Vitest integration for evals.
affected
Developers using `@mastra/factory` or `@mastra/playground-ui` will need to update their code due to breaking changes.
action
Update your code to use the new `sandbox` callback in `@mastra/factory` and replace `Chip`, `ChipsGroup`, and `StatusBadge` with the new `Badge` component.
release_signals
-`@mastra/factory`: `sandbox` config is now a callback instead of an options object; `workdir` and `maxSandboxes` are removed.
-`@mastra/playground-ui`: `Chip`, `ChipsGroup`, and `StatusBadge` components are removed in favor of a single `Badge` component.
This release introduces trace-correlated logging with a new `AdaptableLogger` contract, improves Pino integration, and enhances deployment readiness with worker health checks. It also includes breaking changes to the `@mastra/playground-ui` DataList API and deprecates the legacy logger wrapper path.
affected
Developers using `@mastra/playground-ui` DataList API or custom loggers without adapter support are affected by breaking changes and deprecations.
action
Update custom logger implementations to support the new `AdaptableLogger` contract and migrate `@mastra/playground-ui` DataList API usage to the new patterns.
release_signals
-`@mastra/playground-ui` DataList API cleanup: removed `variant="lined"`, `flushLeft`/`flushRight`, per-cell `height`, and `DataList.MonoCell` (use `DataList.TextCell font="mono"` instead).
This release introduces new storage backends (Elasticsearch and Valkey), sandbox lifecycle improvements, and enhanced observability and scoring capabilities. It also includes breaking changes and deprecations.
affected
Developers using Mastra Code LSP, `@mastra/playground-ui`, or background task storage will need to update their configurations.
action
Review breaking changes and update your codebase accordingly.
release_signals
-Mastra Code LSP is now opt-in (`"lsp": true`)
-`@mastra/playground-ui`: `MarkdownRenderer streaming` no longer paces word-by-word reveal
-
@mastra/core@1.61.0highfeatureAug 24, 2026
August 21, 2026
This release introduces caller-driven experiments, graceful shutdown controls, improved message delivery, and workflow resume concurrency safety. It also adds a multi-turn LLM judge scorer for evaluations.
affected
Users of Mastra's session handling, workflow resumption, and experiment APIs may need to update their code to leverage new features and safety improvements.
action
Review the new features and update your code to leverage the improved session handling, workflow resumption, and experiment APIs.
release_signals
+Caller-Driven Experiments: External orchestrators can now own the experiment loop while Mastra remains the system of record.
+First-Class 'While-Active' Message Delivery: Messages sent while an agent is working are now consistently marked.
@mastra/core@1.60.0highfeatureAug 19, 2026
August 19, 2026
This release introduces durable execution for Agents API, a new Cloudflare Sandbox provider, MCP protocol upgrades, sandbox checkpoints, and persistable GraphRAG snapshots. It also includes various minor improvements and fixes.
affected
Developers using Mastra's Agents API, Cloudflare Sandbox provider, MCP protocol, or RAG features will benefit from new capabilities and performance improvements.
action
Update to @mastra/core@1.60.0 to take advantage of new features and improvements.
release_signals
+Durable execution for Agents API with configurable loop settings and multi-replica durability
+New Cloudflare Sandbox provider for remote workspaces
+MCP protocol upgrades including stateless 2026-07-28 support and multi-round elicitation
This release introduces TokenCostControl with enhanced budgeting features, adds active run introspection capabilities, and improves observability. It includes breaking changes around Factory auto-run behavior and CostGuardProcessor renaming.
affected
Users relying on automatic agent runs in Factory or using CostGuardProcessor will need to update their configurations.
action
Review and update configurations for Factory auto-run behavior and migrate from CostGuardProcessor to TokenCostControl.
release_signals
-Factory: automatic agent runs are now opt-in per Factory (`autoRunEnabled` defaults off on upgrade); rules proposing runs now park them as `proposed` decisions until approved.
This release introduces file-based agent schedules, a new Oracle storage provider, QuickJS in-process Code Mode transport, dynamic workflow enhancements, and custom API route support. It also includes breaking changes for stored workflows and channel reply formats.
affected
Developers using stored workflows or plain-text channel replies will need to update their code to accommodate the breaking changes.
action
Update code to use dynamic workflows instead of stored workflows and configure channel adapters for plain-text replies if needed.
release_signals
-Stored workflows renamed to dynamic workflows: `addStoredWorkflow(s)` → `addDynamicWorkflow(s)`, `StoredWorkflow*` types → `DynamicWorkflow*`, and `workflow.origin` now reports `'dynamic'`.
-Channel agent replies now post as markdown by default; set `textFormat: 'plain'` on channel adapter configs (e.g. Slack) to preserve literal plain-text posting.
@mastra/core@1.57.0highfeatureAug 10, 2026
August 5, 2026
This release introduces several new features including tool result guardrails, transient agent signals, and a new observability exporter. It also includes performance improvements and fixes for memory leaks and session management.
affected
Developers using Mastra for agent-based workflows and tool integrations will benefit from new features like transient signals and tool result processing, while those with long-running processes will see improved memory management.
action
Update to version 1.57.0 to take advantage of new features like transient signals and tool result processing, and to benefit from memory leak fixes and performance improvements.
release_signals
+Tool Result Guardrails via `processToolResult` for scanning, transforming, or aborting tool outputs before they reach the LLM.
+Transient Agent Signals for delivering per-turn context without persistence.
@mastra/core@1.56.0highbreakingfeatureAug 6, 2026
August 5, 2026
This release introduces persistable declarative workflows, enabling workflows to be authored as data and survive restarts. It also adds end-to-end support for stored workflows via HTTP APIs, client SDKs, and database persistence. Additionally, a declarative predicate DSL and nested workflow steps allow for storage-safe conditionals and loops.
affected
Developers using workspace providers need to update their authentication method.
action
Update authentication to use `MASTRA_PLATFORM_ACCESS_TOKEN` or pass `accessToken` explicitly.
release_signals
-Removed `MASTRA_PLATFORM_SECRET_KEY` auth for workspace providers; use platform-injected `MASTRA_PLATFORM_ACCESS_TOKEN` or pass `accessToken` explicitly.
+Persistable declarative workflows with JSON graphs and rehydration
This release introduces in-process Code Mode execution, a new `@mastra/isolated-vm` package for V8-isolated Code Mode, and a built-in provider-native Web Search tool. It also adds `autoPublish` for stored agent drafts and integrates Factory channel identity domains.
affected
Developers using `ChannelHandler` with fewer than four arguments will need to update their code to include the `ctx` parameter.
action
Update any `ChannelHandler` calls to include the `ctx` parameter.
release_signals
-`ChannelHandler` context parameter is now required: the 4th parameter is `ctx: ChannelHandlerContext` (non-optional). Code that calls a `ChannelHandler`-typed function with only three args must be updated to pass `ctx`.
+In-process Code Mode execution with `requiresSandbox: false`
This release introduces chat channel support for AgentController, enhances MongoDB Vector Store with hybrid retrieval, and adds exact metadata filtering for memory queries. It also improves streaming performance and introduces a breaking change for channel handlers.
affected
Developers using channel handlers or memory APIs are affected by the breaking change and new features.
action
Update channel handlers to accept the new `ChannelHandlerContext` argument and review new features for potential integration.
release_signals
-Channel handlers now receive a 4th argument: `ChannelHandlerContext` (use `ctx.mastra` to access the resolved Mastra instance).
+AgentController Chat Channels (Slack/Discord/Telegram, etc.) with native streaming output, tool approval cards, and typing indicators.
This release introduces read-only sandbox options, better control over channel thread IDs, and explicit opt-in for channel reaction tools. It also improves reliability and concurrency in various components.
affected
Users relying on automatic injection of channel reaction tools will need to explicitly add them to their agent's toolset.
action
Update your agent configurations to explicitly include channel reaction tools if needed.
release_signals
-Channel reaction tools (`add_reaction`, `remove_reaction`) are no longer automatically injected into a channel-bearing agent’s toolset; add them explicitly if needed.
+Added `readOnly` option to `LocalFilesystem` and `NativeSandboxConfig` for safer execution on macOS and Linux.
This release introduces sandbox deployments, workspace sandbox networking, and factory storage domains. It also includes enhancements to agent runtime and a new `@mastra/factory` package for reusable route surfaces.
affected
Developers using Mastra for sandbox deployments, workspace sandboxes, and agent runtime will be affected by these changes.
action
Update to version 1.52.0 to take advantage of new features and ensure compatibility with breaking changes.
release_signals
-Bundled Braintrust SDK upgraded from v2 to v3, with narrowed `BraintrustExporterConfig` types and changed `root_span_id` semantics
+Sandbox deployments with `@mastra/deployer-sandbox` for one-step `mastra build`
`@mastra/mcp@2.0.0` is a major rewrite: MCP 2026-07-28 only (legacy handshake removed), suspend/resume replaces elicitation APIs, and several server/client transport and protocol surfaces were removed per the MCP v2 migration guide.
+New vector stores: Azure AI Search + Weaviate
+Observability trace querying gets 'real' pagination, discovery, and delta polling
+Durable-agent performance: stop persisting `running` checkpoints by default
+Token-budgeted conversation history trimming with `messageHistory`
+Make the workspace grep text-extension whitelist extensible