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 substantial Knowledge capabilities, including a page-tree model, richer tools, server-side sync APIs, and read-only HTTP/JS client APIs with an SSE change stream. It also improves durable-agent continuity, resumable background task flows, trace filtering, and streaming latency metrics, while changing several Knowledge, memory, Temporal, and Factory APIs.
affected
Mastra Core users building Knowledge features, durable agents, workflows, or trace-query integrations are affected; users of the removed APIs or deprecated `getStepResult` need to update their code.
action
Review the breaking changes and replace removed or deprecated APIs; configure shared fencing-capable storage and pubsub if durable agents must continue across API process loss.
release_signals
-`@mastra/temporal@0.5.0` now validates `inputSchema` and `requestContextSchema` before steps run; invalid inputs may fail runs that previously succeeded. Set `validateInputs: false` to opt out.
-`experimental_subconscious` and the Memory `knowledge` option are removed and now throw; Knowledge must be attached to the Agent, and older Subconscious/Coordinator constructors now throw.
-`knowledge.reindex()` is removed; use page or note upserts, and `reindexLinks()` for link indexing.
-`@mastra/factory@0.27.0` removes `claimKey` and related work-item claiming methods and types.
!`getStepResult` is deprecated and planned for removal in a future major release; `getStepResultAsync` is its replacement.
+Agent `scopes` functions can narrow or replace incoming run scopes, subject to preserving any supplied `resource:` and `thread:` scopes.
+
migration_steps5 steps
01For Temporal steps, correct inputs to satisfy `inputSchema` and `requestContextSchema`, or set `validateInputs: false` to opt out.
02Attach Knowledge to the Agent instead of using the removed Memory `knowledge` option or experimental Subconscious/Coordinator APIs.
03Replace `knowledge.reindex()` with page or note writes; call `reindexLinks()` when rebuilding the link index.
04Replace `getStepResult` with awaited `getStepResultAsync`; update tests that construct step execute parameters manually to provide `getStepResultAsync`.
05For evented-agent continuity across API loss, configure fencing-capable shared storage such as `PostgresStore` and shared pubsub.
This release adds storage-backed MCP tasks designed to resume across instances and restarts, plus broader background-task support and richer observability for outcomes, stop reasons, model/provider, and time-to-first-token. It also introduces saved-view and dashboard schemas, authenticated channel attachment handling, browser cookie support, and factory-scoped sandbox environments. The notes identify breaking API and subpath removals across packages, including changes to `@mastra/playground-ui` and `@mastra/core`.
affected
The release affects Mastra users building long-running tasks, observability dashboards, channel-enabled agents, browser sessions, and factory sandboxes, while consumers of the removed or changed APIs need to update their integrations.
action
Review the breaking UI and core API changes and update observability consumers to handle nullable fields before upgrading.
This release introduces agent scopes for multi-tenant identity and safer memory/thread routing, a new trace aggregation API, and typed signal queueing for agents. It also improves trace list usability with stored input/output/error previews and enhances reliability for long-running workflows.
affected
Users leveraging agent scopes, trace aggregation, or factory sessions will be affected by these changes.
action
Upgrade `@mastra/server` and review breaking changes and deprecations to ensure compatibility.
release_signals
-`buildInputPreview()` and `INPUT_PREVIEW_MAX_LENGTH` are deprecated in favor of `buildPreview()` and `PREVIEW_MAX_LENGTH`.
This release introduces significant enhancements to Mastra Factory, including new sandbox providers, environment builds, and multi-repo sessions. It also improves durable agent safety with run fencing and observational memory concurrency, while adding trace linking for better cross-system observability.
affected
Developers using Mastra Factory, durable agents, and observational memory will be affected by these changes.
action
Review breaking changes and update your code accordingly, especially if using Factory projects, workflow HTTP routes, or AgentController.
release_signals
-Factory projects now support provider-instance sandboxes; existing callback form lacks these capabilities.
-@mastra/server workflow HTTP routes no longer allow starting/resuming internal workflows.
This release introduces enhanced tool context access to conversation states, improved observational memory history search capabilities, and new accessible form field primitives in the Playground UI. It also includes breaking changes in the Playground UI components.
affected
Developers using `@mastra/playground-ui` and Convex users are directly affected by the breaking changes and migration requirements.
action
Convex users should redeploy their Mastra server functions to apply new observational memory history filters.
release_signals
-`anchorTraceId` removed from `ThreadViewByTrace`, `TraceThreadPanel`, and `ThreadTrace`; `ThreadTrace.LoadMoreSentinel` removed. Use `pageSize` and `onLoadOlder` on `ThreadTrace` to control pagination/loading older turns.
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.
Advanced trace queries now support `requestId`, `serviceName`, and `experimentId` filters.
+`ClassifierProcessor` adds `onDecision` for recording classification outcomes and supports tripwire metadata on aborts.
+Evented durable agents can continue across API process shutdown when run fencing and shared infrastructure are configured.
+Knowledge gains a page-tree model, richer read/list/link tools, server-side sync APIs, read-only browsing APIs, and an SSE change stream.
-
`@mastra/playground-ui` removes or changes metrics chart card APIs, including `ChartCard` properties, several `MetricsCard` components, and related table/legend APIs.
-`@mastra/playground-ui` removes `useFluidHover`, `FluidHoverHighlight`, and `CommandList.highlightClassName`.
-`@mastra/core` removes runtime-importable subpaths `@mastra/core/network/vNext` and `@mastra/core/telemetry/otel-vendor`.
-Public observability `outcome`, `stopReason`, and `stopReasonContext` fields now allow `null`; exporters and consumers must account for null values as well as absent values.
!Factory sandbox environment functions enable credential scoping by `factoryId`; the notes caution that factory names are editable and not unique.
!`MastraBrowser.setCookies()` supports authenticated browser sessions, and cookie values do not pass through the model.
!Workspace channel attachment storage is capped at 100 MiB by default to limit disk use; oversized or otherwise unavailable files fall back to a URL.
!`defineBoard()` and `MastraFactory`'s `boards`/`includeDefaultBoards` are deprecated in favor of stored boards APIs.
!Deprecated board fields `title`, `role`, and `next` should move to `name`, `runner.context`, and `nextPhases`, respectively.
+Experimental storage-backed MCP tasks support long-running execution with polling, answering, cancellation, restart safety, and unified tracing.
+Background tasks support non-agent owners, per-task expiration and metadata, per-owner concurrency overrides, and queued resumes.
+Observability adds execution outcomes and typed stop reasons, model/provider fields, and time-to-first-token metrics, with query and store support.
+Adds schemas for saved observability views and dashboards, and playground UI support for dashboard rendering and saved views.
+Channel agents can save authenticated binary attachments into workspaces; also adds browser `setCookies()` and factory-scoped sandbox environments.
migration_steps4 steps
01For removed `@mastra/core` subpaths, stop importing `@mastra/core/network/vNext` and `@mastra/core/telemetry/otel-vendor`; the notes say these paths no longer ship.
02Update observability exporters and consumers to handle `null` values for `outcome`, `stopReason`, and `stopReasonContext`.
03Replace deprecated factory board APIs with stored boards APIs, and migrate board fields from `title`/`role`/`next` to `name`/`runner.context`/`nextPhases`.
04When removing a credential from a factory, recreate its running Platform or Docker sandboxes; resumed sandboxes retain the environment with which they started.