Mastra Release - 2025-08-27

We're thrilled to announce the release of support for Zod v4, while maintaining compatibility with Zod v3! We've also revamped our observability under the new name ai-tracing (documentation is on the way). Plus, you'll discover improvements in our streamVNext and generateVNext methods.

General

• Support for the PATCH HTTP method in custom API routes and updates related tests. #7006
• Enable support for Zod v4 #6942
• Update Zod peer dependency to version 3.25 to support both v3/v4. #7032
• Update AI peer dependencies to include version 5, resolving npm installation issues. #6982

Agents

• Issues with type resolution and includes an associated changeset. #6996
• The output processor to use a new stream format, cleans up related documentation, and fixes associated tests. #6927
• A new convertMessages utility to @mastra/core, enabling seamless conversion between various message formats (Mastra, AI SDK v4/v5, and others) while preserving metadata, addressing the need for a public message conversion API. #6864

Client SDK - JS

• A 'credentials' option to the client-js library's fetch requests, allowing users to control cookie and authentication header behavior, with updated interfaces, tests, and documentation. #6972
• Linting for client-js and fixes related type issues. #6993
• Support for Zod v4 while maintaining compatibility with Zod v3, updates the schema compatibility and test suite, uses toJsonSchema from Zod, and upgrades autoform to v4. #6944
• The internal output schema handling in the streaming pipeline for improved TypeScript generics, type safety, and documentation, without changing the user-facing API. #6949

Deployer

• The esm-shim plugin to resolve module format ambiguity errors during 'mastra dev' by ensuring compatibility between CommonJS and ES module syntax. #6914
• Disable the esm-shim plugin in the Cloudflare deployer. #7017

Scorers (Evals)

• A tool-call-accuracy scorer using both LLM and code-based approaches, along with corresponding documentation and tests. #6861
• Comprehensive tests for the InMemoryLegacyEvals.getEvals method, covering field transformation, pagination, agent and type filtering, empty collection handling, and data integrity, increasing test coverage by 39 lines. #6984

Observability

• A database schema for AI trace spans and introduces a base observability storage class with default method stubs, creating AI span tables only if supported. #6954
• Renamed AITraceContext to TraceContext and parentAISpan to parentSpan for clearer and more consistent naming in AI-related code. #6989
• Server APIs and a client SDK for fetching AI traces from Mastra storage. #6967
• A new 'isEvent' column to the 'mastra_ai_spans' table to indicate whether a span is an event. #7020
• AI tracing APIs to the in-memory mock store and includes corresponding test cases. #6957
• New APIs for storing AI spans and traces in Libsql, along with related tests. #6959
• Mastra objects in workflow steps using JavaScript proxies to automatically inject tracing context into nested agent and workflow calls, simplifying trace continuity and renames 'parentSpan' to 'currentSpan' in the TracingContext object. #7011
• A bug where an error occurred if the 'mastra' object was undefined in a step when AI Tracing is enabled. #7026

Storage

• A new getMessagesById method to all MastraStorage adapters, enabling retrieval of messages by their IDs. #6700
• The ClickHouse column and execution engine utilities that were missed during a previous storage adapter refactor, ensuring they are available for cloud usage. #6928

Workflows

• Reusable utility functions for workflow information to the server handlers and updates core processors to be asynchronous. #6933
• Workflow run status to 'running' and persists step information in storage when a step starts, addressing issue #6936 and including related test updates. #6943
• A bug to ensure that workflow run state is preserved after viewing traces in the Mastra Playground. #6948
• AI tracing for Mastra workflows by introducing detailed span types for improved observability, fixes typing issues, and adds basic test coverage. #6971
• A proof-of-concept event-based workflow execution engine and a general-purpose event engine integrated with the Mastra class, featuring support for pluggable PubSub adapters. #6923
• Workflow types, likely restructuring or refactoring type definitions related to workflows. #7018

Examples

• A multi-turn human-in-the-loop example to the documentation. #7010