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.
Mastra adds resumable run streams for every Agent, with replay, cross-instance observation, and abort support. The release also introduces a built-in MCP server with OAuth configuration, expands experimental workflow storage v2 to Postgres and libSQL, and adds resumable AI SDK chat routes and one-off or bounded schedules.
affected
Mastra users building agents, MCP integrations, workflows, chat routes, or schedules are affected; users relying on checkpoint-backed execution through `Agent.durable` must update their setup.
action
If you use `Agent.durable` for checkpoint-backed execution, migrate to `createDurableAgent({ agent })` and review disconnect behavior for plain agents with resumable streams enabled.
release_signals
-`Agent`'s `durable` option now controls resumable streams, not checkpoint-backed durable execution. Use `createDurableAgent({ agent })` for durable execution; plain-agent disconnect behavior also differs when streams are enabled.
+Every Agent can publish resumable run streams with replay caching and observe/abort APIs.
+Built-in MCP endpoint at `/api/mcp`, configurable toolsets and routes, plus OAuth discovery and token-audience checks.
+Experimental workflow `storageVersion: 2` now supports Postgres and libSQL, persisting per-step changes.
+Resumable AI SDK chat routes support `chatRoute({ resumable: true })` and reconnect GET endpoints.
+Agent and workflow schedules can run once with `runAt` or recur until `endAt`.
migration_steps1 steps
01For checkpoint-backed durable execution, migrate to `createDurableAgent({ agent })`.
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.
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 adds user-scoped OAuth connections and connection prompts, span aggregation, richer provider-error classification, and improved durable-run controls. It also introduces experiment-specific model selection and render-only tools, alongside several breaking API changes affecting tracing, Connect sessions, code-sdk subagents, and Playground UI sorting.
affected
Applications using Mastra connections, trace queries, code-sdk subagents, or Playground trace sorting are affected by API changes; observability and agent applications can also use the new connection, aggregation, error-handling, and run-control capabilities.
action
Review the breaking API changes and update affected consumers before upgrading.
release_signals
-`queryTraceThreads()` no longer returns `model` or `provider` in thread rows; `page.limit` defaults to 25, is capped at 100, and larger values fail validation.
Mastra Core 1.79.0 adds experimental MCP event delivery and inspection, span aggregation and richer observability queries, native sandbox filesystem support, and user-scoped Connect integrations with Microsoft Teams support. It also changes agent controller sessions to use session IDs and updates several query and routing contracts, requiring corresponding changes in affected clients and storage adapters.
affected
Users of agent controller sessions, thread or span queries, channel resolution, durable-run observation, or observability storage adapters are affected; MCP, sandbox, and Connect users can adopt the new capabilities.
action
Review and update controller, query, channel, durable-observation, and storage-adapter integrations for the documented contract changes 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 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 automatic error recovery for agents, a new stream chunk for better tool interaction UX, and adds Google Workspace toolsets. It also includes reliability fixes for durable execution and improvements in observational memory.
affected
Users of durable streams and those relying on the `tripwire` chunk behavior are affected by the breaking change.
action
Review and update code to accommodate the breaking change in durable streams and consider leveraging the new features for improved error handling and tool interaction.
release_signals
-Durable streams no longer emit a separate `tripwire` chunk when an output processor blocks; use `finishReason === 'tripwire'` and `output.tripwire` instead.
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.
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.
`@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.
+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.
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.
`@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.
-`POST /connect/:provider/sessions` now returns `launchUrl` instead of `connectUrl`.
-`@mastra/code-sdk` no longer registers built-in subagents by default.
-`TracesExplorer` sorting now takes one `{ field, direction }` object instead of `sortDirection` and `onSortDirectionChange`.
!Resource-scoped connections enforce that one user's connection cannot be used for another user.
+Add per-resource OAuth connections through `tools({ resourceId })` and `userConnectRoutes()`, with a `request_connection` tool for prompting users to connect missing providers.
+Add span aggregation through `POST /observability/spans/aggregate` and `aggregateSpans()` for ClickHouse, Postgres, and DuckDB.
+Add provider-error classification and persisted error identity helpers, with provider details available to clients and aligned retry classification.
+Add `agentModel` to dataset agent experiments and introduce render-only tools, span preview generation, and additional native span fields.
+Add ordered thread-run status subscription outcomes and explicit durable-run cancellation through `agent.abortRun(runId)`.
migration_steps4 steps
01Pass `subagents: [...builtinSubagents]` to `@mastra/code-sdk` to retain the previous built-in subagent behavior.
02Update consumers of connect-session creation to read `launchUrl` instead of `connectUrl`.
03Update `TracesExplorer` sorting integrations to use the `{ field, direction }` API.
04Adjust `queryTraceThreads()` consumers for the removed `model` and `provider` fields, and keep page limits at or below 100.
Agent controller sessions are keyed by `sessionId`; `scope` and `getSessionByResource()` are removed, and controller APIs, server routes, and client-js signatures change.
-Thread-row query contract changes to `timeRange.traces` and `timeRange.threads` instead of `traces.timeRange`.
-`querySpans()` removes `model` and `provider` filters and no longer returns `cost`, `inputTruncated`, `outputTruncated`, or `errorTruncated`; storage adapters must match the revised contract.
-Channel `resolveResourceId` and `resolveThreadId` contexts now require `requestContext`.
-Cross-process `DurableAgent.observe(runId)` now rejects runs whose persisted agent ID differs, with `DURABLE_AGENT_OBSERVE_AGENT_MISMATCH`.
!Session creation rejects an explicit `resourceId` that differs from the resource of an existing live session with that ID, preventing use of a session ID to take over another resource's session.
!Connect adds per-resource end-user connection scoping to prevent one user's connections from serving another user's requests; MCP webhook events are described as signed.
+Experimental MCP Events support polling, streaming, signed webhooks, and Studio inspection and test emission.
+Adds the `aggregateSpans()` storage contract and span aggregation, plus expanded trace/span query fields and `timeToFirstChunkMs` filtering and sorting.
+Adds optional native filesystem operations to `WorkspaceSandbox`, adopted by `@mastra/code-sdk` for faster file operations.
+Adds per-resource end-user scoping and `userConnectRoutes()` to `@mastra/connect`, and Microsoft Teams as a supported channel.
+Agent controller sessions can now be independently identified by session ID, allowing multiple sessions per resource.
migration_steps5 steps
01Replace controller session `scope` usage with a distinct session `id`; use `controller.getSession(sessionId)` and pass `{ sessionId }` to `deleteSession()`.
02Update thread-row queries to use `timeRange.traces` and `timeRange.threads`.
03Update `querySpans()` callers and storage adapters for the removed filters and response fields.
04Pass `requestContext` to channel `resolveResourceId` and `resolveThreadId` contexts.
05When observing a durable run across processes, use the same agent ID as the agent that started it.