Mastra Release Notes

Highlights

Span Query API (list completed spans across traces)

New core/server/client support lets you query individual completed spans (with filters, cursors, previews, and model cost) via storage.querySpans() / client.querySpans() / POST /api/observability/spans/query, enabling workflows like “show every failed tool_call in the last hour” without first finding traces.

Trace Aggregation with token + cost analytics (now across stores)

aggregateTraces() now supports token and cost measures (tokens.* sums/avgs and cost.sum/cost.avg with coverage + currency handling), and is implemented in the ClickHouse, DuckDB, and Postgres observability stores—making cost/tokens-first dashboards and “top spenders” queries a first-class capability.

Self-embedding vector stores for Semantic Recall (no client embedder required)

Semantic recall can now run against vector stores that generate embeddings themselves (MastraVector.isSelfEmbedding), including MongoDBVector via autoEmbed, so memory recall and message writes work without configuring a client-side embedder.

@mastra/connect 1.0: new channels/providers capabilities (Teams, Discord credential security) + better observability …

Highlights

Tool Context Can Read the Full Conversation (agent.getMessages())

Tools now have access to the current conversation state via context.agent.getMessages() in both standard and durable agent loops, including remembered messages and in-run responses—enabling richer, context-aware tool behavior without changing the existing input-only messages field.

Observational Memory History Search (Filtering, Ordering, Record Lookup)

getObservationalMemoryHistory gained group filtering (groupId), explicit ordering (sortDirection), and direct lookup by recordId, with adapter capability signaling via supportsObservationalMemoryHistorySearch (notably affecting multiple DB adapters; Convex requires a server function redeploy for the new filters to apply).

Memory Recall Can Page Through Observation Groups Around Search Hits

Recall now supports paging “before/after” from a matched groupId, including groups condensed by reflection and buffered-but-not-yet-activated groups—improving investigation workflows without requiring re-indexing, alongside clearer, chronologically ordered search results and better first-turn retrieval guidance.

Playground UI: New Accessible Form Field Primitives (Field, Fieldset, Form, SearchInput) …

Highlights

Live channel resolvers (no-redeploy channel connections)

Mastra({ channels }) now accepts a resolver function (via channels() in @mastra/connect) so channel connections added/removed on Mastra Platform appear on a running server without redeploy; use mastra.resolveChannels() to fetch the current provider map at runtime.

Multi-worker safety for background tasks via persisted ownership leases

Background task execution is now lease-fenced (persisted ownerId + expiring lease) so multiple managers can share one storage without double-running tasks or allowing stale workers to overwrite results; storage adapters were updated to enforce expectedOwnerId/lease write conditions.

Stronger durability & recovery for agents/workflows (including evented engine fixes)

Durable and evented agents/workflows get major correctness upgrades: safer crash recovery, preserved timeouts across serialization, proper tool/result processing & transcript transforms on durable runs, savePerStep honored, and EventedAgent is back on the built-in evented engine with recovery support.

Thread streaming and PubSub retention improvements (faster reconnects, less replay) …

Highlights

Observability Capabilities Negotiation (Storage ↔ Server ↔ Client)

Servers now expose observabilityStorageCapabilities (via GET /system/packages and the new GET /observability/capabilities) so Studio/clients can detect which observability APIs a configured store actually supports—covering per-endpoint discovery flags plus traceQuery, threadQuery, deltaPolling, and more—without forcing storage upgrades.

Discovery-Backed Observability Filters & Feature Declarations

Observability stores can now declare supported features via getFeatures() (including entity/service/environment/tag/metric discovery), letting Studio only call compatible endpoints; VNext stores and Oracle now report discovery support, and discovery routes return empty results (not 500s) when unsupported.

Trace Aggregation Planning API for Backends

planTraceAggregate() validates and converts an aggregateTraces() request into a TrustedTraceAggregatePlan that any storage backend can execute without re-validating, enabling consistent query behavior and clearer validation errors across storage implementations.

Eager Tool Execution for Faster Streaming Runs

Tool calls now start as soon as their own arguments are complete (instead of waiting for the model to finish streaming the whole step), cutting idle time in multi-tool steps; can be disabled per run (and is now supported in stored agent default options). …

Highlights

Classifiers as a First-Class Primitive (Core + Workflows)

Mastra now supports registering classifiers on new Mastra({ classifiers }), with a full management API (getClassifier*, listClassifiers, addClassifier, removeClassifier) and automatic root tracing for classifier evaluations. Those configured classifiers can also be used as typed workflow steps (including fluent + dynamic graphs) to power typed branching/conditional control flow with token usage.

Policy Enforcement with ClassifierProcessor (Input/Output/Streaming)

New ClassifierProcessor lets you apply typed classifier policies to agent input, output, and streaming content, enabling safety/routing gates with explicit abort behavior. It now fails closed by default (abort on classifier failure), with an opt-in errorStrategy: 'warn' to preserve prior fail-open behavior.

Native Background Tool Execution with context.background.adopt()

Tools can now acknowledge immediately while handing a long-running native background operation to Mastra via context.background.adopt({ completion, cancel }), so execution can track completion/cancellation without keeping execute() pending. This enables cleaner async/background tool patterns (with the caveat that adopted handles are in-memory and don’t resume after restart).

Connected SaaS Tools at Scale via @mastra/connect (New Generated Providers) …

Highlights

MCP v2 (2026-07-28) server architecture in @mastra/mcp@2.0.0

@mastra/mcp is now rebuilt on the MCP 2026-07-28 revision: no initialize handshake/session headers, and tools that need input use first-class suspend/resume (context.suspend() + context.resumeData) with signed, self-contained continuation state (requestState). Server routes now return explicit { status: 'suspended', suspendPayload, resumeSchema } vs { status: 'completed', output }.

New vector stores: Azure AI Search + Weaviate

Two new MastraVector backends land: @mastra/azure-ai-search@0.1.0 (Azure AI Search with auto-indexed filterable metadata for Memory/RAG) and @mastra/weaviate@0.1.0 (full MastraVector contract with rich Mongo-style metadata filtering and deterministic vector ID mapping).

Observability trace querying gets “real” pagination, discovery, and delta polling (core/server/client + ClickHouse/DuckDB/PG)

Advanced trace queries now support page-based pagination (with totals), bounded field/value discovery APIs, and delta polling cursors to transition from initial load → incremental updates efficiently. Trace list results also include root-span summary fields (name, createdAt, metadata, inputPreview, etc.) so UIs can render useful lists without fetching full traces.

Durable-agent performance: stop persisting running checkpoints by default …

Highlights

Studio Workflow Builder Backend (persisted workflows)

A new Studio Workflow Builder backend can be enabled via the workflowBuilder editor option, adding an editor-owned agent that authors persisted workflow definitions plus new server endpoints (GET /editor/workflow-builder/settings, POST /editor/workflow-builder/stream) gated by stored-workflow permissions.

New @mastra/connect Package (platform integrations → agent tools)

@mastra/connect turns Mastra Platform integration connections into agent tools that execute through the platform connection proxy (credentials injected + token refresh) so your app never handles provider secrets; it supports live discovery/refresh of connected tools and optional allowlisting via integrations.

Thread Ownership Transfer (resourceId reassignment)

Threads can now be transferred to a new resourceId with Memory.updateThreadResourceId({ threadId, resourceId }), a new server route POST /memory/threads/:threadId/transfer, and client-js support via MemoryThread.transfer(), with transactional/serialized implementations across major SQL adapters (and vector migration when semantic recall is enabled).

More Powerful Background Tool Execution Controls …

Highlights

Deploy-scoped worker provisioning for Mastra Cloud

@mastra/deployer can now statically emit a versioned workers.json manifest (when shared storage + PubSub are configured) to provision dedicated orchestration/scheduler/background/custom workers, and runtime workers expose an authenticated endpoint so Cloud can compare live topology vs build-time.

Advanced trace queries: richer filtering across span fields, metadata, feedback, and scores (with DB support)

Trace querying gains high-power predicates for same-span properties (model/provider, duration, outcome, identity, lineage), portable top-level metadata.* predicates, and richer feedback / scores filters—supported end-to-end in @mastra/server plus @mastra/pg, @mastra/clickhouse, and @mastra/duckdb.

Observability signal deletion (feedback + scores) across storage, server, and client

Core observability storage adds idempotent batch deleteFeedback() / deleteScores() (with optional org/resource scoping), with corresponding DELETE /api/observability/* routes in @mastra/server and client methods in @mastra/client-js; ClickHouse/DuckDB/Postgres (and others) implement backend handling.

Observational Memory transform hooks

@mastra/memory adds async transform hooks (beforeObservation, afterObservation, beforeReflection, afterReflection) so apps can filter/redact/reshape messages and generated observations/reflections before model calls or persistence. …

Highlights

Advanced Trace Querying (Core Contract + Server Endpoints + Storage Implementations)

Mastra now has a strict, portable “advanced trace query” contract (bounded time ranges, recursive predicates, thread grouping, deterministic cursor pagination) plus an authenticated server endpoint for it, with real implementations in ClickHouse, DuckDB, and Postgres.

Tenant-Scoped Trace Deletion + Trace Cascade Cleanup (Experiments & API)

You can delete up to 1,000 traces per request with tenant scoping, and deletion now cascades across spans and trace-linked signals (scores, feedback, metrics, logs). Experiment deletion now also cleans up the traces the experiment produced (including orphaned experiments), exposed in core APIs, server routes, and client-js methods.

Workflow Graph Metadata for Control-Flow Blocks

Control-flow entries (parallel/branch/loops/foreach/sleep/map, etc.) now support optional id, description, and metadata, surviving serialization and rehydration so visual editors/review tools can label and stably address blocks (not just executable steps).

Agent Channel Actions API (Handle Button Clicks / Select Changes)

Agent channels gained handlers.onAction so apps can handle interactive UI card actions (e.g., “retry” buttons) while still delegating to Mastra’s built-in approval handler (or disabling it).

Factory Custom Boards Become First-Class (Installable, Typed, UI + Policy/Rules Ownership) …

Highlights

Reusable Sandbox Templates + Warm Repo Checkouts (E2B & Platform)

New reusable template APIs in @mastra/platform-workspace plus @mastra/e2b repo templates let sandboxes start from a pre-cloned, pre-built repository image (with background rebuilds and resource sizing), dramatically reducing cold-start time for code sessions and workspace-backed agents.

Unified workingDirectory Across All Sandbox Providers

A new workingDirectory option in MastraSandboxOptions is now honored by every sandbox provider (with a sandbox.workingDirectory getter), standardizing default command/process CWD behavior across Docker/E2B/Vercel/Railway/etc. while still allowing per-command cwd overrides.

Client-Side Tools Can Use Server-Defined toModelOutput

Client-executed tools (browser tools without execute) now support server-defined toModelOutput, so the server can transform the returned payload into model-ready content (e.g., turning { fileId, dataUrl } into an image content part) without custom input processors.

Observability Feedback Review Workflow (API + Storage + UI Plumbing)

Feedback records now support reviewStatus (needs-review/reviewed) with filtering in listFeedback, a new storage method updateFeedbackReviewStatus, and a new server endpoint PATCH /api/observability/feedback/:feedbackId/review-status exposed in @mastra/client-js.

New @mastra/evals/vitest Test Runner Integration …

Highlights

Trace-correlated logging via the new logger adapter contract

A new AdaptableLogger contract in @mastra/core/logger standardizes trace correlation by injecting trace_id/span_id into native log records during traced operations, and deriving observability LogEvents from the same record. Mastra now supports loggerOptions to control correlation and log export, and the legacy dual-write wrapper path is deprecated.

First-class Pino integration with trace context in every transport

@mastra/loggers’ PinoLogger now implements the adapter contract, so trace fields are added via a pino mixin to stdout, files, and custom transports—while preserving user mixin fields. This aligns native application logs with Mastra observability without separate logging pipelines.

More reliable trace/log linking for non-exported spans (no more “Span not found”)

Across @mastra/core and @mastra/observability, logs/metrics emitted inside internal or excluded spans now link to the nearest ancestor span that actually reaches exporters, and omit spanId when none exists. This fixes broken click-through from Studio and ensures stdout correlation matches stored observability records.

Deployment readiness improvements: worker health gating …

Highlights

Caller-Driven Experiments (Temporal/External Orchestrator Support)

New dataset experiment APIs let external orchestrators own the experiment loop while Mastra remains the system of record: create experiments idempotently, run items server-side (runExperimentItem) or submit externally computed results (submitExperimentResult), then finalize for server-computed succeeded/failed/skipped counts—fully compatible with Studio views and comparisons.

Graceful Shutdown + HTTP Drain Controls for Generated Servers

Generated servers now support configurable shutdown behavior (drain in-flight requests, tune drainTimeout, or disable built-in signal handlers) with improved shutdown draining behavior and cleanup reliability across @mastra/core and @mastra/deployer.

First-Class “While-Active” Message Delivery in Sessions

User messages sent while an agent is already working are now consistently marked delivery: 'while-active' automatically (including steering), simplifying clients and preserving accurate transcripts across reloads while keeping caller overrides supported.

Workflow Resume Concurrency Safety (Atomic Claim + 409 Conflicts)

Concurrent resume() calls are now safe: a resume atomically claims a suspended run (losers get WORKFLOW_RESUME_ALREADY_CLAIMED and HTTP 409), and workflow state updates add an expectedStatus guard to prevent duplicate downstream execution.

Evals: Multi-Turn LLM Judge Scorer …

Highlights

Durable execution for Agents API (no deploy required)

Stored agents created via the Agents API can now run with durable: true, enabling durable execution (with configurable loop settings) without shipping new code, and inheriting cache/pubsub from your server for multi-replica durability.

Cloudflare Sandbox provider for remote workspaces

The new @mastra/cloudflare-sandbox provider runs commands and file operations via a deployed Sandbox Bridge Worker, adding a new deployment/runtime option for Mastra workspaces.

MCP protocol upgrades: stateless 2026-07-28 + multi-round elicitation

@mastra/mcp adds opt-in support for the stateless 2026-07-28 protocol revision (server + client) plus updated elicitation support using the spec’s multi round-trip mechanism, enabling more modern MCP interoperability without breaking legacy connections.

Sandbox checkpoints (Local + Platform/Railway capability signaling)

Sandboxes now advertise supportsCheckpoints, and LocalSandbox gains filesystem-backed checkpoints (checkpointName/seedCheckpointName) so sessions can boot from and persist real snapshots—unlocking faster warm-start patterns (also supported in Platform and Railway sandboxes).

RAG: persistable GraphRAG snapshots

@mastra/rag adds serialize() and GraphRAG.deserialize() so knowledge graphs can be saved/restored instead of rebuilt on every start, dramatically reducing startup cost for large corpora. …

Highlights

TokenCostControl (renamed from CostGuard) with richer budgeting

CostGuardProcessor is now TokenCostControl (id: 'token-cost-control') with better diagnostics/reliability and new budgeting options like warnAtPercent, per-request maxCost functions, new cost scopes (user/organization/session), and optional per-model/provider breakdowns.

Active run introspection for agents/controllers (core, server, client-js)

New Agent.listActiveThreadRuns() / AgentController.listActiveThreadRuns() plus corresponding Server + JS client APIs let you cheaply list in-flight runs from in-memory tracking—ideal for polling activity indicators without creating sessions.

Observability fixes: external-parent traces now show up as trace roots in Studio

Tracing bridges (OTel + Datadog) now mark whether a span’s parent is external vs Mastra, fixing missing traces when runs start under an external parent so they correctly appear as trace roots in Mastra Studio.

Safer/more useful redaction with indexed tokens

SensitiveDataFilter gains redactionStyle: 'indexed', producing stable per-value tokens (e.g. [APIKEY_1]) instead of collapsing all sensitive values to [REDACTED], improving debugging while preserving secrecy.

Memory recall continuation for oversized message parts …

Highlights

File-based Agent Schedules

File-based agents can now declare recurring tasks via a schedules/ directory (TS or Markdown) that syncs to schedule storage at startup, eliminating runtime registration code and making schedule IDs stable across builds.

New Storage Provider: @mastra/oracledb

Added @mastra/oracledb with OracleStore (composite storage across Mastra domains) and OracleVector (Oracle 23ai+ VECTOR columns with metadata filtering), enabling Oracle Database-backed deployments.

QuickJS In-Process Code Mode Transport (@mastra/quickjs)

New @mastra/quickjs transport runs model-authored programs in an in-process QuickJS WASM runtime (no native addon, no --no-node-snapshot), enabling Code Mode on more serverless hosts without a full sandbox.

Dynamic Workflows: Workflow Builder API + Code SDK Management

Dynamic workflows gain a reusable Workflow Builder authoring API (createWorkflowBuilderAgent) plus Mastra Code SDK support for discovery-backed creation, persistence, execution, and deletion of workflows.

Custom createRoute() API Routes Across Server + Adapters

createRoute() routes can now be registered via server.apiRoutes with native validation/auth/streaming/OpenAPI support on @mastra/server, and are supported in server adapters (Hono/Express/Fastify/Koa) for consistent typed routing.

Breaking Changes …

Highlights

Tool Result Guardrails via processToolResult

A new processToolResult processor lifecycle hook runs after each tool execution and before results enter message history, enabling prompt-injection/sensitive-data scanning, transformation, or aborting the run before the LLM sees tool output.

Transient Agent Signals (Per-turn Context Without Persistence)

Signals now support transient: true end-to-end (@mastra/core, @mastra/server, @mastra/memory, and typed support in @mastra/client-js) so you can deliver “reminder” context to the current model call without retaining it in stored conversation/observational memory.

New Observability Exporter: @mastra/deepeval

Introduces @mastra/deepeval, an exporter that sends Mastra traces to Confident AI (DeepEval) for evaluation and monitoring, mapping Mastra spans into Confident’s agent/LLM/tool/retriever/custom types with tokens, tool calls, and metrics.

Better Tooling Visibility in Traces + PostHog LLM Analytics

Model generations now capture full tool definitions (name/description/JSON schema) as a tools attribute on MODEL_GENERATION spans, and @mastra/posthog forwards these as $ai_tools so analytics can show exactly which tool schemas each generation ran with.

Much Faster Mastra Platform Sandbox Exec (Private Network Direct Dial) …

Highlights

In-process Code Mode execution (no workspace sandbox required)

Code Mode transports can now declare requiresSandbox: false, letting createCodeMode() run without a workspace sandbox for in-process execution boundaries. This enables secure in-process runtimes like V8 isolates and exports sanitizeToolId so transports can share consistent external_* naming.

New @mastra/isolated-vm package for V8-isolated Code Mode

Introduces @mastra/isolated-vm with IsolatedVmCodeModeTransport, running model-authored programs inside an in-process V8 isolate with no filesystem/network/process access (only bridged external_* tools). Note: requires isolated-vm native addon and Node 20+ hosts must start with --no-node-snapshot.

Built-in provider-native Web Search tool

@mastra/core adds webSearchTool, a first-party web search tool that resolves to provider-native search when supported by the configured model/provider, simplifying “current info” agent setups.

Stored agent drafts via autoPublish (Server + JS SDK)

Both @mastra/server and @mastra/client-js add autoPublish to stored agent creation so you can create an initial unpublished draft for review before publishing (existing calls still publish immediately by default).

New Factory channel identity domain + channels integration slot …

Highlights

AgentController Chat Channels (Slack/Discord/Telegram, etc.)

AgentController can now run durable agent sessions inside chat threads via Chat SDK adapters, with native streaming output, tool approval cards, typing indicators, and controller-owned webhook routes at /api/agent-controllers/<CONTROLLER_ID>/channels/<PLATFORM>/webhook.

MongoDB Vector Store: Bring-Your-Own Collections + Hybrid (Vector + Full-text) Retrieval

MongoDBVector can now index existing operational collections (with safe, read-only-by-default semantics), return full source documents via metadataMode: 'document', and add full-text + hybrid retrieval via createSearchIndex, textQuery, and hybridQuery (Atlas Search / MongoDB 8.0+).

Exact Metadata Filtering Across Memory APIs and Storage Providers

Message history queries (memory.recall) now support exact-match metadata filtering with AND semantics, implemented across Memory APIs and supported backends (e.g. pg, mysql, mongodb, redis, clickhouse, cloudflare, dynamodb, spanner, etc.).

Smoother Streaming for Agents and AI SDK Routes

New smoothStream() plus experimental stream transforms buffer text/reasoning deltas into consistent chunks, and the AI SDK now supports the same smoothing via handleChatStream(), chatRoute(), and toAISdkStream().

Faster PlatformSandbox Exec via Direct WebSocket Data Plane …

Highlights

Read-only local sandbox & filesystem support

New readOnly options on LocalFilesystem and NativeSandboxConfig let you run local sandboxes with a read-only working directory on macOS (Seatbelt) and Linux (Bubblewrap) for safer execution.

Custom thread ID resolution for channels

ChannelConfig.resolveThreadId lets hosts control the internal Mastra thread id for newly created channel threads (after resolveResourceId), enabling clean alignment with external IDs like session IDs.

Explicit channel reaction tools (less implicit agent tool injection)

Channel reaction tools (add_reaction, remove_reaction) are no longer auto-injected into channel-bearing agents; if you want reactions, you now opt in by adding channels.getTools().

Stored agent versioning: auto-publish on update

@mastra/client-js adds autoPublish to stored agent updates so you can immediately activate a newly created agent version as part of the update call.

Reliability & concurrency improvements across Factory + stores

Factory work-item processing now uses atomic claims/idempotent replay (replacing distributed advisory locks), and @mastra/libsql fixes concurrent-write data loss/corruption in observational memory by serializing updates; composite-store “disabled domain” observability/score endpoints now return clear 501 responses instead of 500s.

Breaking Changes …

Highlights

Sandbox Deployments + One-Step mastra build (New @mastra/deployer-sandbox)

You can now deploy a full Mastra server (including Studio) into networking-capable workspace sandboxes (Vercel/E2B/Daytona) and get a live URL in seconds via the new @mastra/deployer-sandbox. Push-style deployers can opt into deployOnBuild, making mastra build bundle and deploy in one step (SandboxDeployer already opts in).

Workspace Sandbox Networking, Bulk File Uploads, and Cloning (Fleet-Ready Sandboxes)

WorkspaceSandbox gained optional networking.getPortUrl(port) plus writeFiles() for bulk uploads, enabling preview URLs and faster sandbox provisioning; multiple providers now implement this (notably Vercel/E2B/Daytona). Sandboxes also add clone() to create unstarted sibling sandboxes from a template config—ideal for per-project or per-tenant sandbox fleets.

Factory Storage Domains + New Pg/LibSQL “FactoryStorage” Backends

A new FactoryStorage contract and FactoryStorageDomain enable lifecycle-managed, per-domain application storage initialization/readiness/error reporting, rather than a single monolithic store. New backends PgFactoryStorage and LibSQLFactoryStorage persist Mastra agent state plus custom app domains through one shared Postgres pool/LibSQL connection.

New @mastra/factory Package (Software Factory Extraction + Reusable Route Surfaces) …