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 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.
release_signals
-`@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.
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.
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 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 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.
!
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.
-`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.