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 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.
+File-based agent schedules via a `schedules/` directory for stable schedule IDs across builds.
+New `@mastra/oracledb` storage provider with `OracleStore` and `OracleVector` for Oracle Database-backed deployments.
+QuickJS in-process Code Mode transport (`@mastra/quickjs`) for running model-authored programs in a WASM runtime.
+Dynamic workflows with Workflow Builder API and Code SDK support for creation, persistence, execution, and deletion.
+Custom `createRoute()` API routes with native validation/auth/streaming/OpenAPI support across server and adapters.
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`
This release introduces significant new features, including realtime voice agents with LiveKit, file-system routed Mastra primitives, and a unified schedules API. It also includes breaking changes related to the renaming of heartbeats to schedules and improvements in observability and workspace provider registry.
affected
Users relying on heartbeats and related APIs will need to migrate to the new schedules API.
action
Update your code to use the new schedules API and migrate any deprecated heartbeat methods.
release_signals
-Heartbeats renamed to schedules: `mastra.heartbeats` → `mastra.schedules`, config `heartbeat` → `schedules`, type renames (e.g., `Heartbeat` → `AgentSchedule`), new agent schedule IDs use `agent_`, and the default fire signal tag is now `<schedule>`.
@mastra/core@1.49.0highbreakingfeatureJul 7, 2026
July 3, 2026
This release introduces opt-in storage retention policies, multi-tenant isolation for datasets and experiments, and new APIs for scoring stored traces. It also includes agent authoring improvements, new workspace/sandbox options, and breaking changes in the Playground UI.
affected
Users relying on `@mastra/playground-ui` root named exports or `Searchbar` component will need to update their imports and UI compositions.
action
Update imports from `@mastra/playground-ui` to use explicit subpaths and replace `Searchbar` with `InputGroup`.
release_signals
-`@mastra/playground-ui` removed root named exports; import from explicit subpaths.
-`@mastra/playground-ui` removed `Searchbar`; use `InputGroup` composition instead.
+
@mastra/core@1.48.0highbreakingfeatureJul 1, 2026
July 1, 2026
This release introduces scheduled agents via cron-based heartbeats, file-based agent definitions with auto-registration, and upgrades to observational memory and durable execution. It also includes breaking changes for Vercel sandbox naming and AgentController interval APIs.
affected
Users of Vercel sandbox exports or AgentController interval APIs need to update their code.
action
Update any references to the renamed Vercel sandbox exports and AgentController interval APIs.
release_signals
-Vercel sandbox exports renamed: VercelSandbox now means MicroVM-backed Vercel Sandbox, serverless implementation is now VercelServerlessSandbox
-AgentController interval API renamed: heartbeatHandlers is now intervalHandlers, HeartbeatHandler type is now IntervalHandler, removeHeartbeat()/stopHeartbeats() methods are now removeInterval()/stopIntervals()
@mastra/core@1.47.0highbreakingfeatureJul 1, 2026
June 26, 2026
This release introduces support for AI SDK v7 models, enhances the `DurableAgent` API to mirror `Agent` functionality, and centralizes model discovery and auth via the new `GatewayManager`. Additionally, `Harness` is renamed to `AgentController` with enriched session state and thread scoping.
affected
Users of `Harness`, `DurableAgent`, and model discovery/auth configurations are affected by the breaking changes and need to migrate to the new `AgentController` and `GatewayManager`.
action
Update your code to use `AgentController` instead of `Harness` and migrate model discovery/auth configurations to `GatewayManager`.
release_signals
-Harness→AgentController migration: legacy `/harness/...` routes and `harness:*` permissions removed
-`@mastra/client-js` removed deprecated `getHarness`/`listHarnesses` and `Harness`/`HarnessSession` classes
This release introduces multi-session architecture with isolated session management, HTTP harness operations, and cross-process signal delivery. It also adds deterministic agent experiments and new integrations.
affected
Users of Harness singleton and direct API calls will need to migrate to session-based operations.
action
Update code to use the new session-based APIs for state, events, and run control.
release_signals
-Harness no longer exposes a singleton harness.session; must use harness.createSession()
-Run control moved from Harness to Session (e.g., sendMessage, abort)
This release introduces trusted system actor execution for workflows, tools, and agents, enabling server-side/background work without JWT/human membership requirements. It also adds a new SignalProvider framework for declarative agent signal wiring and makes task tools agent-agnostic with durable thread state storage.
affected
Developers using Harness APIs for question handling and plan approval will need to migrate to the new tool suspension APIs.
action
Update code to use `respondToToolSuspension` and handle `tool_suspended` events instead of deprecated question and plan approval APIs.
release_signals
-Removed `harness.respondToQuestion(...)` → use `harness.respondToToolSuspension(...)`
-Removed `ask_question` event → listen for `tool_suspended` and read `event.suspendPayload`
+
Stored workflows end-to-end: HTTP APIs, client SDK, and DB persistence
+Declarative predicate DSL and nested workflow steps for storage-safe conditionals/loops