github mastra-ai/mastra @mastra/core@1.14.0
March 17, 2026
on GitHub

16 hours ago

Highlights

AI Gateway Tool Support in the Agentic Loop

@mastra/core now supports AI Gateway tools (e.g. gateway.tools.perplexitySearch()) as provider-executed tools: it infers providerExecuted, merges streamed provider results back into the originating tool calls, and skips local execution when the provider already returned a result.

More Reliable Observational Memory (Cache Stability + “As Of” Retrieval)

Observational memory persistence is more stable via dated message boundary delimiters and chunking, and @mastra/memory adds getObservationsAsOf() to retrieve the exact observation set active at a given message timestamp (useful for replay/debugging and consistent prompting).

MCP Client Diagnostics & Per-Server Control

@mastra/mcp adds per-server operational tooling—reconnectServer(serverName), listToolsetsWithErrors(), and getServerStderr(serverName)—to improve reliability and debugging of MCP stdio/server integrations.

Breaking Changes

  • None called out in this changelog.

Changelog

@mastra/core@1.14.0

Patch Changes

  • Update provider registry and model documentation with latest models and providers (51970b3)

  • Added dated message boundary delimiters when activating buffered observations for improved cache stability. (#14367)

  • Fixed provider-executed tool calls being saved out of order or without results in memory replay. (Fixes #13762) (#13860)

  • Fix generateEmptyFromSchema to accept both string and pre-parsed object JSON schema inputs, recursively initialize nested object properties, and respect default values. Updated WorkingMemoryTemplate type to a discriminated union supporting Record<string, unknown> content for JSON format templates. Removed duplicate private schema generator in the working-memory processor in favor of the shared utility. (#14310)

  • Fixed provider-executed tool calls (e.g. Anthropic web_search) being dropped or incorrectly persisted when deferred by the provider. Tool call parts are now persisted in stream order, and deferred tool results are correctly merged back into the originating message. (#14282)

  • Fixed replaceString utility to properly escape $ characters in replacement strings. Previously, patterns like $& in the replacement text would be interpreted as regex backreferences instead of literal text. (#14434)

  • Fixed tool invocation updates to preserve providerExecuted and providerMetadata from the original tool call when updating to result state. (#14431)

  • @mastra/core: patch (#14327)

    Added spanId alongside traceId across user-facing execution results that return tracing identifiers (including agent stream/generate and workflow run results) so integrations can query observability vendors by run root span ID

  • Add AI Gateway tool support in the agentic loop. (#14016)

    Gateway tools (e.g., gateway.tools.perplexitySearch()) are provider-executed but, unlike native provider tools (e.g., openai.tools.webSearch()), the LLM provider does not store their results server-side. The agentic loop now correctly infers providerExecuted for these tools, merges streamed provider results with their corresponding tool calls, and skips local execution when a provider result is already present.

    Fixes #13190

  • Fixed schema-based working memory typing so workingMemory.schema accepts supported schemas such as Zod and JSON Schema. (#14363)

  • Fixed workspace search being wiped when skills refresh. Previously, calling skills.refresh() or triggering a skills re-discovery via maybeRefresh() would clear the entire BM25 search index, including auto-indexed workspace content. Now only skill entries are removed from the index during refresh, preserving workspace search results. (#14287)

  • Added client/server body schemas for feedback and scores that omit the timestamp field, allowing it to be set server-side (#14270)

  • Fixed processor state not persisting between processOutputStream and processOutputResult when processors are wrapped in workflows. State set during stream processing is now correctly accessible in processOutputResult. (#14279)

  • Fixed type inference for requestContext schemas when using Zod v3 and v4. Agent and tool configurations now correctly infer RequestContext types from Zod schemas and other StandardSchema-compatible schemas. (#14363)

@mastra/ai-sdk@1.1.4

Patch Changes

  • Clarified that chatRoute() aborts generation on client disconnect and documented a custom route pattern that continues server-side generation with consumeStream(). (#14333)

@mastra/auth@1.0.2

Patch Changes

  • Fixed Studio showing unauthenticated state when using MastraJwtAuth with custom headers. MastraJwtAuth now implements the IUserProvider interface (getCurrentUser/getUser), so the Studio capabilities endpoint can resolve the authenticated user from the JWT Bearer token. (#14411)

    Also added an optional mapUser option to customize how JWT claims are mapped to user fields: 

    new MastraJwtAuth({
  secret: process.env.JWT_SECRET,
  mapUser: payload => ({
    id: payload.userId,
    name: payload.displayName,
    email: payload.mail,
  }),
});

    Closes #14350

@mastra/auth-studio@1.2.0

Minor Changes

  • Add configurable cookie domain support (#14285)
    • Add cookieDomain option to MastraAuthStudioOptions for explicit configuration
    • Support MASTRA_COOKIE_DOMAIN environment variable as fallback
    • Use hostname-based detection for auto-detecting .mastra.ai domain (prevents false positives from malicious URLs)
    • Maintain backward compatibility with existing .mastra.ai auto-detection

Patch Changes

@mastra/client-js@1.9.0

Minor Changes

  • Added new observability API endpoints and client methods for logs, scores, feedback, metrics (aggregate, breakdown, time series, percentiles), and discovery (metric names, label keys/values, entity types/names, service names, environments, tags) (#14270)

Patch Changes

@mastra/deployer@1.14.0

Patch Changes

  • Added MASTRA_HOST environment variable support for configuring the server bind address. Previously, the host could only be set via server.host in the Mastra config. Now it follows the same pattern as PORT: config value takes precedence, then env var, then defaults to localhost. (#14313)

  • Added a new MASTRA_TEMPLATES Studio runtime flag to control whether the Templates section appears in the sidebar. (#14309)

    • MASTRA_TEMPLATES=true now enables Templates navigation in Studio.
    • By default (false or unset), Templates is hidden.
    • Studio HTML injection now propagates this value in both CLI-hosted and deployer-hosted Studio builds.
    • Added tests covering environment variable injection for both paths.

  • Fixed tsconfig path aliases during build when imports use .js-style module specifiers. (#13998)

  • Fixed apiPrefix server option not being applied to the underlying Hono server instance. Routes, welcome page, Swagger UI, and studio HTML handler now all respect the configured apiPrefix instead of hardcoding /api. (#14325)

@mastra/deployer-cloudflare@1.1.12

Patch Changes

  • Stop writing .env variables to wrangler.jsonc to prevent secrets from leaking into source control. (#14302)
    • Environment variables from .env are no longer merged into the vars field of the generated wrangler config.
    • User-provided vars from the CloudflareDeployer constructor are still written as before.
    • A warning is logged during build with instructions to upload secrets via npx wrangler secret bulk .env.

@mastra/elasticsearch@1.2.0

Minor Changes

  • Added support for constructing ElasticSearchVector with a pre-configured Elasticsearch client. You can now pass either a client instance or connection parameters (url and optional auth), giving you full control over client configuration when needed. (#12802)

    Using connection parameters: 

    const vectorDB = new ElasticSearchVector({
  id: 'my-store',
  url: 'http://localhost:9200',
  auth: { apiKey: 'my-key' },
});

    Using a pre-configured client: 

    import { Client } from '@elastic/elasticsearch';

const client = new Client({ node: 'http://localhost:9200' });
const vectorDB = new ElasticSearchVector({ id: 'my-store', client });

Patch Changes

@mastra/libsql@1.7.1

Patch Changes

  • Added dated message boundary delimiters when activating buffered observations for improved cache stability. (#14367)

@mastra/loggers@1.0.3

Patch Changes

  • Fixed: PinoLogger now supports JSON output for log aggregators (#14306)

    Previously, PinoLogger always used pino-pretty which produced multiline
    colored output, breaking log aggregators like Datadog, Loki, and CloudWatch.
    A new prettyPrint option allows switching to single-line JSON output.

@mastra/mcp@1.3.0

Minor Changes

  • Added new MCP client APIs for per-server control and diagnostics. (#14377)

    • Added reconnectServer(serverName) to reconnect a single MCP server without restarting all servers.
    • Added listToolsetsWithErrors() to return both toolsets and per-server errors.
    • Added getServerStderr(serverName) to inspect piped stderr for stdio servers.

    Example 

    const { toolsets, errors } = await mcpClient.listToolsetsWithErrors();
await mcpClient.reconnectServer('slack');
const stderr = mcpClient.getServerStderr('slack');

Patch Changes

  • Improved (#14260)

    • Updated @modelcontextprotocol/sdk from ^1.17.5 to ^1.27.1.

    Deprecated

    • Deprecated prompt version usage in @mastra/mcp.
    • Prompt versions are not part of MCP protocol behavior and will be removed.

    Migration

    • Use unique prompt names instead of prompt versions.
    • Before: client.prompts.get({ name: 'explain-code', version: 'v1', args })
    • After: client.prompts.get({ name: 'explain-code-v1', args })
    • MastraPrompt is available for migration and is also deprecated.

@mastra/memory@1.8.3

Patch Changes

  • Fixed observational memory triggering observation while provider-executed tool calls are still pending, which could split messages and cause errors on follow-up turns. (#14282)

  • Fixed working memory tool description to accurately reflect merge behavior. The previous description incorrectly stated "Set a field to null to remove it" but null values are stripped by validation before reaching the merge logic. The updated description clarifies: omit fields to preserve existing data, and pass complete arrays or omit them since arrays are replaced entirely. (#14424)

  • Limit oversized observational-memory tool results before they reach the observer. (#14344)

    This strips large encryptedContent blobs and truncates remaining tool result payloads to keep observer prompts and token estimates aligned with what the model actually sees.

  • Improved observational memory cache stability by splitting persisted observations into separate prompt chunks using dated message boundary delimiters. (#14367)

    Added getObservationsAsOf() utility to retrieve the observations that were active at a specific point in time. This enables filtering observation history by message creation date. 

    import { getObservationsAsOf } from '@mastra/memory';

// Get observations that existed when a specific message was created
const observations = getObservationsAsOf(record.activeObservations, message.createdAt);

@mastra/mongodb@1.5.6

Patch Changes

  • Added dated message boundary delimiters when activating buffered observations for improved cache stability. (#14367)

@mastra/pg@1.8.1

Patch Changes

  • Added dated message boundary delimiters when activating buffered observations for improved cache stability. (#14367)

@mastra/playground-ui@17.0.0

Minor Changes

  • Added dedicated session page for agents at /agents/<agentId>/session. This minimal view shows only the chat interface without the sidebar or information pane, making it ideal for quick internal testing or sharing with non-technical team members. If request context presets are configured, a preset dropdown appears in the header. (#13754)

    Added hideModelSwitcher prop to AgentChat and Thread components to allow hiding the model picker in the composer.

Patch Changes

  • Fixed crash during template installation by ensuring error values from stream events are converted to strings before being passed to the UI. This prevents the 'e?.includes is not a function' TypeError when the server returns non-string error payloads. (#14267)

  • Fixed crash when template installation errors are non-string values (e.g. objects). The error is now safely converted to a string before calling .includes(), preventing the 'e?.includes is not a function' TypeError in the studio. (#14267)

@mastra/schema-compat@1.2.5

Patch Changes

  • Added ZodIntersection support so that MCP tools using allOf in their JSON Schema no longer throw 'does not support zod type: ZodIntersection'. Intersection types are flattened and merged into a single object schema across all provider compatibility layers (Anthropic, Google, OpenAI, OpenAI Reasoning, DeepSeek, Meta). (#14255)

@mastra/server@1.14.0

Minor Changes

  • Added new observability API endpoints and client methods for logs, scores, feedback, metrics (aggregate, breakdown, time series, percentiles), and discovery (metric names, label keys/values, entity types/names, service names, environments, tags) (#14270)

Patch Changes

  • Fixed server tool serialization for plain JSON Schema objects to prevent tools from disappearing in Studio. (#13920)

Other updated packages

The following packages were updated with dependency changes only:

Check out latest releases or
releases around mastra-ai/mastra @mastra/core@1.14.0

Don't miss a new mastra release

NewReleases is sending notifications on new releases.

Get notifications