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 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 durable agent run ownership for crash recovery, atomic working-memory merges in PostgreSQL, and improved file-handling resilience. Observational Memory now defaults to `model: 'auto'`, and trace nesting enhances observability.
affected
Users relying on PostgreSQL for working memory, file-handling workflows, or Observational Memory defaults are most affected.
action
Review and update your code to handle the new Observational Memory defaults and PostgreSQL merge behavior.
release_signals
-`@mastra/playground-ui`: Old Metrics card views/components were removed.
-`@mastra/playground-ui`: `MetricsCardGroup` no longer accepts `variant`; `MetricsLineChart` dropped `xAxisInterval`/`xAxisMinTickGap`.
-
@mastra/core@1.75.0highbreakingfeatureOct 7, 2026
October 7, 2026
This release introduces significant enhancements to observability and trace aggregation, self-embedding vector stores for semantic recall, and a stable version of @mastra/connect with improved credential security and provider capabilities. Sessions now persist a single active model per thread, and several breaking changes have been implemented.
affected
Developers using @mastra/connect, AgentController model switching, and @mastra/react hooks are affected by breaking changes.
action
Review breaking changes and update code accordingly, especially for @mastra/connect, AgentController, and @mastra/react hooks.
release_signals
-@mastra/connect@1.0.0: discovered MCP tools no longer require approval by default; use `requireApproval` to opt in
-@mastra/connect: API rename `integrations` → `providers`; removed legacy surfaces
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 dynamic channel resolvers for live updates without redeploy, enhances background task safety with persisted ownership leases, improves durability and recovery for agents/workflows, and adds thread streaming optimizations. Observability upgrades include trace aggregation and richer filtering.
affected
Developers using `session.respondToToolApproval` or `@mastra/playground-ui` APIs are affected by breaking changes.
action
Update code to include `toolCallId` in `session.respondToToolApproval` and review `@mastra/playground-ui` API changes.
release_signals
-`session.respondToToolApproval(...)` now requires `toolCallId`
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 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.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.
`@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.
`@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