mastra-ai/mastra @mastra/core@1.31.0

May 1, 2026

on GitHub

Highlights

Platform Channels Framework (Core + Server + Client)

A new channels architecture adds ChannelProvider, a dedicated ChannelsStorage domain, and ChannelConnectResult connection flows (OAuth, deep link, immediate), with Mastra-level connect/disconnect/list APIs and matching MastraClient.channels methods.

Slack Channel Integration (@mastra/slack)

New Slack provider connects agents to Slack workspaces with OAuth-based app provisioning, manifest drift detection, encrypted credential storage, slash commands, and threaded conversation support.

NestJS Server Adapter (@mastra/nestjs)

New @mastra/nestjs adapter runs Mastra inside NestJS (Express) apps with native module registration, DI-friendly service injection, rate limiting, graceful shutdown, streaming, and MCP transport support; MastraServerBase is now exported to support adapters that manage routing.

Google Drive Workspace Filesystem (@mastra/google-drive)

New Google Drive WorkspaceFilesystem mounts a single Drive folder as an agent workspace, supporting OAuth tokens (with refresh callbacks) and service accounts, and implementing the full read/write/list/move/stat interface with optimistic concurrency via expectedMtime.

Real-time Voice Provider for AWS Nova Sonic (@mastra/voice-aws-nova-sonic)

Adds a bidirectional streaming voice provider for Bedrock Nova 2 Sonic with live mic streaming and playback, streaming transcription (speculative/final), barge-in detection, multi-voice selection, and tool calling with per-session RequestContext.

Breaking Changes

• @mastra/playground-ui: IconButton export removed (use Button with size="icon-*") and <Alert> removed in favor of <Notice>; variant="light"/"inputLike" replaced by variant="default".

Changelog

@mastra/core@1.31.0

Minor Changes

• Enhanced load_tool to accept an array of tool names, enabling bulk tool loading in a single call. Returns 'loaded', 'notFound', and 'alreadyLoaded' arrays for clearer response shape. (#15472)

• Added Microsoft Entra ID authentication support for Azure OpenAI gateways, so Azure deployments can call models without API keys when using Azure SDK credentials. (#15983)

• Added platform channels framework with ChannelProvider interface, ChannelsStorage domain, and ChannelConnectResult discriminated union supporting OAuth, deep link, and immediate connection flows. Channels can be registered on the Mastra instance and expose connect/disconnect/list APIs for platform integrations. (#15876)

• Added top-level environment config on Mastra to tag observability signals with the deployment environment. (#15956)

  Set it once on the Mastra instance and it will be attached to all observability signals automatically. Falls back to process.env.NODE_ENV when unset; per-call tracingOptions.metadata.environment still takes precedence.

  Before

  await agent.generate('hello', {
    tracingOptions: { metadata: { environment: process.env.NODE_ENV } },
  });

  After

  new Mastra({
    environment: 'production',
    observability: new Observability({ ... }),
  })

  mastra.getEnvironment() returns the resolved value.

• Fixed trajectory scorers in dataset.startExperiment receiving raw agent messages instead of a Trajectory object, which caused a crash when accessing run.output.steps. Trajectory scorers now receive the same pre-extracted Trajectory that runEvals provides. (#15693)

  The scorers option now also accepts the same categorised shape as runEvals (AgentScorerConfig / WorkflowScorerConfig), so you no longer need to rewrite your scorer config when moving from runEvals to dataset.startExperiment.

  Before (trajectory scorer crashed at runtime):

  await dataset.startExperiment({ scorers: [orderScorer] }) // run.output.steps was undefined

  After (works correctly, both flat and categorised forms accepted):

  await dataset.startExperiment({ scorers: [orderScorer] })
  await dataset.startExperiment({ scorers: { agent: [accuracyScorer], trajectory: [orderScorer] } })

  Per-step scorers are now also supported for workflow targets, matching runEvals. Pass scorers: { workflow: [...], steps: { stepId: [...] }, trajectory: [...] } to score individual workflow steps with their own scorers; results carry the originating stepId and keep targetScope: 'span' (with targetEntityType: WORKFLOW_STEP on the underlying scorer run), matching how runEvals encodes step identity.

• Workspace search now supports batch-capable embedders. Pass an embedder branded with batch: true (and an optional maxBatchSize) to embed all pending chunks for a flush in a single provider call instead of one call per chunk. This dramatically reduces index-rebuild time on large workspaces when using providers that support batch embedding (e.g. OpenAI's embedMany). Existing single-text embedders continue to work unchanged. (#14735)

  import { embedMany } from 'ai';
  import { openai } from '@ai-sdk/openai';
  
  const model = openai.embedding('text-embedding-3-small');
  
  const workspace = new Workspace({
    // ...
    embedder: Object.assign(
      async (texts: string[]) => {
        const { embeddings } = await embedMany({ model, values: texts });
        return embeddings;
      },
      { batch: true as const, maxBatchSize: 2048 },
    ),
  });

Patch Changes

• Update provider registry and model documentation with latest models and providers (1723e09)

• Fixed workflow runs not being cancellable when steps or conditions ignored the abort signal. Cancelling a run now correctly stops dountil, dowhile, and foreach loops at every cancellation boundary — between iterations, after a step returns, after the loop condition is evaluated, and (for foreach) between concurrency chunks and after the final chunk. Previously, long-running loops (e.g. a dountil with a setTimeout inside the step) would keep running and eventually emit success even after the run was cancelled. Closes #15990. (#15994)

• Fixed type inference on workflow loop helpers (foreach, dowhile, dountil) so a step's requestContextSchema correctly aligns with the workflow's requestContextSchema. Previously these methods dropped the workflow's TRequestContext from the step parameter, causing TypeScript to reject typed-context steps even when the workflow declared a matching schema. Steps without a requestContextSchema are still accepted; steps whose schema does not match the workflow's now produce a type error. Fixes #15989. (#15995)

• Fixed sub-agent delegation so nested tool results stay out of the parent model context by default while remaining available to application code. Set delegation.includeSubAgentToolResultsInModelContext to include the full subagent result in the parent model context. (#15832)

• Added a coalesced display state subscription API for Harness. (#15974)

  This helps UI clients render fewer updates while still receiving the latest state. The example below renders the initial state, then subscribes to coalesced updates with the default windowMs and maxWaitMs timing options.

  render(harness.getDisplayState());
  
  const unsubscribe = harness.subscribeDisplayState(render, {
    windowMs: 250,
    maxWaitMs: 500,
  });

• Fixed BatchPartsProcessor using a hardcoded id in batched text-delta chunks. The real message id and runId are now preserved from the original chunks, preventing AI SDK UIMessage stream from dropping batched deltas. (#14974)

• Add filterAfterToolSteps to ToolCallFilter so tool calls can be filtered during agentic loops after they are no longer recent. By default, ToolCallFilter keeps its previous behavior and only filters the initial input. (#15795)

• Workspace search no longer throws when requesting hybrid or vector mode if the configuration does not support it. The search tool now gracefully falls back to the best available mode instead of throwing an error. (#14533)

• Workspace file tools no longer use misleading absolute-path examples (e.g. /data/output.txt) that caused weaker LLMs to attempt writes at the actual filesystem root. The example paths in read_file and write_file are now relative. (#14544)

  Additionally, when a contained workspace rejects an absolute path that escapes its boundary, the resulting PermissionError now guides the agent toward a relative path so it can self-correct on the next turn. When the path's first segment names a real directory in the workspace (e.g. /src/app.ts with an existing src/), the error suggests the exact relative form. Otherwise it falls back to a generic hint instead of inventing a misleading suggestion for genuinely out-of-workspace paths like /etc/passwd.

  Fixes #14542

• Fixed SkillSearchProcessor so agents use it as the on-demand skill discovery path without also adding eager skill context. (#15916)

  When SkillSearchProcessor is configured, agents no longer auto-add the eager SkillsProcessor, and they hide the overlapping skill and skill_search tools while keeping skill_read available for supporting skill files. Workspace file tools can still read SKILL.md files during explicit file inspection or editing workflows.

• Fixed tool calls to run in parallel when active tools exclude approval or suspending tools. (#15978)

• • SearchEngine: indexMany uses p-map with a default concurrency of 8 when vector embedding runs, with optional concurrency and stopOnError (same semantics as p-map). Lazy vector indexing flushes pending documents at the same concurrency, drains the queue before awaiting so concurrent index calls are not dropped, loops until the queue is empty before search, dedupes by document id (last wins), and re-queues the batch if a flush throws. (#14735)
  • Workspace: Search auto-indexing reads files in parallel with a bounded concurrency, skips unreadable paths, awaits batch indexing, and falls back to per-file indexing when the batch path throws. Successful single-file indexing returns the path so callers can track what was indexed.

• Fix semantic recall indexing to honor read-only memory mode. (#15949)

• Fixed Linux bubblewrap failing when Workspace mounts use symlinks under LocalSandbox by resolving mount paths to real directories for isolation allowlists. (#15498)

@mastra/arize@1.0.22

Patch Changes

• Renamed emitted OTel GenAI cache usage attributes to match the OpenTelemetry semantic conventions: (#15966)

  • gen_ai.usage.cached_input_tokens → gen_ai.usage.cache_read.input_tokens
  • gen_ai.usage.cache_write_tokens → gen_ai.usage.cache_creation.input_tokens

  gen_ai.usage.input_tokens is unchanged and remains the total prompt-token count. Cache attributes are emitted separately as subsets of that total.

  Updated Arize, Arthur, and Sentry mappings so cache values continue to flow through those exporters.

  Direct consumers should update any dashboards, alerts, or queries that reference the old attribute names.

@mastra/arthur@0.2.8

Patch Changes

• Renamed emitted OTel GenAI cache usage attributes to match the OpenTelemetry semantic conventions: (#15966)

  • gen_ai.usage.cached_input_tokens → gen_ai.usage.cache_read.input_tokens
  • gen_ai.usage.cache_write_tokens → gen_ai.usage.cache_creation.input_tokens

  gen_ai.usage.input_tokens is unchanged and remains the total prompt-token count. Cache attributes are emitted separately as subsets of that total.

  Updated Arize, Arthur, and Sentry mappings so cache values continue to flow through those exporters.

  Direct consumers should update any dashboards, alerts, or queries that reference the old attribute names.

@mastra/clickhouse@1.6.0

Minor Changes

• Added ClickhouseStoreVNext, a ClickHouse storage adapter that uses the vNext observability domain by default. Equivalent to constructing a ClickhouseStore and overriding the observability domain manually, but exposed as a single class for new projects. (#15984)

  import { Mastra } from '@mastra/core';
  import { ClickhouseStoreVNext } from '@mastra/clickhouse';
  
  export const mastra = new Mastra({
    storage: new ClickhouseStoreVNext({
      id: 'clickhouse-storage',
      url: process.env.CLICKHOUSE_URL!,
      username: process.env.CLICKHOUSE_USERNAME!,
      password: process.env.CLICKHOUSE_PASSWORD!,
    }),
  });

  ClickhouseStoreVNext accepts the same configuration as ClickhouseStore and reuses the same ClickHouse client across every domain. ClickhouseStore continues to work for projects on the legacy observability schema.

Patch Changes

@mastra/client-js@1.16.0

Minor Changes

• Added Channels resource to MastraClient with listPlatforms, listInstallations, connect, and disconnect methods for managing platform channel integrations. (#15876)

Patch Changes

@mastra/convex@1.0.9

Patch Changes

• Fixed Convex workflow snapshot loads to use the workflow/run index. (#15971)

@mastra/dynamodb@1.0.5

Patch Changes

• Fixed an issue where automatic thread title generation was skipped when using the DynamoDB storage adapter. The adapter was overwriting empty thread titles with a Thread <id> placeholder on save, which prevented the title-generation step (gated on an empty title) from running. Empty titles now round-trip correctly so generated titles work the same as with other storage adapters. Resolves #15998. (#16003)

@mastra/fastify@1.3.16

Patch Changes

• Fix multipart file handling in Fastify adapter by aligning return type with other adapters and preventing stream hang on file size limit. (#15796)

• Fix multipart upload tests to register the multipart content-type parser. The tests were manually adding the preHandler hook but skipping registerContextMiddleware(), which meant Fastify rejected multipart/form-data requests with 415 Unsupported Media Type. (#16002)

@mastra/google-drive@0.1.0

Minor Changes

• Add @mastra/google-drive, a new Google Drive WorkspaceFilesystem provider that mounts a single Drive folder as an agent workspace. Supports OAuth access tokens, async refresh callbacks, and service account (JWT) authentication. Implements the full WorkspaceFilesystem interface — read, write, list, copy, move, mkdir, rmdir, stat, exists — plus expectedMtime optimistic concurrency. (#15756)

  import { Agent } from '@mastra/core/agent';
  import { Workspace } from '@mastra/core/workspace';
  import { GoogleDriveFilesystem } from '@mastra/google-drive';
  
  const workspace = new Workspace({
    filesystem: new GoogleDriveFilesystem({
      folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
      accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
    }),
  });
  
  const agent = new Agent({
    id: 'drive-agent',
    name: 'Drive Agent',
    model: 'openai/gpt-4o-mini',
    workspace,
  });

  A matching googleDriveFilesystemProvider descriptor is also exported for MastraEditor.

Patch Changes

• GoogleDriveFilesystem tweaks: mkdir defaults to recursive, appendFile uses optimistic concurrency, rmdir skips redundant child listing, JSON body requests include Content-Type header, readFile uses consistent searchParams, and concurrent token refreshes are deduplicated. (#16010)

@mastra/libsql@1.9.1

Patch Changes

• Added platform channels framework with ChannelProvider interface, ChannelsStorage domain, and ChannelConnectResult discriminated union supporting OAuth, deep link, and immediate connection flows. Channels can be registered on the Mastra instance and expose connect/disconnect/list APIs for platform integrations. (#15876)

@mastra/mongodb@1.7.4

Patch Changes

• Removed unsupported minScore query option from MongoDB vector store docs and README. Exported MongoDBQueryVectorParams so callers can type documentFilter for MongoDBVector.query(). (#15936)

  Fixes #15715

@mastra/nestjs@0.1.0

Minor Changes

• Add NestJS server adapter (@mastra/nestjs) for running Mastra with NestJS Express applications. Provides native module registration, DI-based service injection, rate limiting, graceful shutdown, streaming, and MCP transport support. (#12751)

  import { Module } from '@nestjs/common';
  import { MastraModule } from '@mastra/nestjs';
  import { mastra } from './mastra';
  
  @Module({
    imports: [MastraModule.register({ mastra })],
  })
  export class AppModule {}

Patch Changes

@mastra/observability@1.11.0

Minor Changes

• Auto-attach the Mastra-level environment to all observability signals. (#15956)

Patch Changes

@mastra/otel-exporter@1.0.21

Patch Changes

• Renamed emitted OTel GenAI cache usage attributes to match the OpenTelemetry semantic conventions: (#15966)

  • gen_ai.usage.cached_input_tokens → gen_ai.usage.cache_read.input_tokens
  • gen_ai.usage.cache_write_tokens → gen_ai.usage.cache_creation.input_tokens

  gen_ai.usage.input_tokens is unchanged and remains the total prompt-token count. Cache attributes are emitted separately as subsets of that total.

  Updated Arize, Arthur, and Sentry mappings so cache values continue to flow through those exporters.

  Direct consumers should update any dashboards, alerts, or queries that reference the old attribute names.

@mastra/perplexity@0.1.0

Minor Changes

• Added new @mastra/perplexity integration with the Perplexity Search tool for agents. (#15939)

  import { createPerplexityTools } from '@mastra/perplexity';
  
  const { perplexitySearch } = createPerplexityTools({ apiKey: process.env.PERPLEXITY_API_KEY });

Patch Changes

@mastra/pg@1.9.4

Patch Changes

• Fixed workflow snapshot sanitization in @mastra/pg for strings containing escaped surrogate patterns like [^\ud800-\udfff]. This prevents invalid JSON escape sequences that caused PostgreSQL jsonb writes to fail with error 22P02. (#15923)

  Fixes #15920

• Added platform channels framework with ChannelProvider interface, ChannelsStorage domain, and ChannelConnectResult discriminated union supporting OAuth, deep link, and immediate connection flows. Channels can be registered on the Mastra instance and expose connect/disconnect/list APIs for platform integrations. (#15876)

@mastra/playground-ui@25.0.0

Minor Changes

• Refactored Button component to use a single cva (class-variance-authority) variant config instead of nested manual maps. Consolidated IconButton into Button via size="icon-sm|icon-md|icon-lg" and removed the IconButton export. Replaced variant="light" and variant="inputLike" with variant="default" (no behavior change for default styling). Added cta and outline variants and unified active/hover styles between text- and icon-mode buttons. (#15985)

  Why: A single source of truth for variants means consistent visuals, fewer drift bugs, simpler maintenance, and a more predictable surface for AI agents — single-variant cva is the dominant shadcn pattern across DS components in this repo (Card, Input, Label, Textarea, StatusBadge).

  Migration:

  // Before
  import { IconButton } from '@mastra/playground-ui';
  <IconButton><Settings /></IconButton>
  <Button variant="light">…</Button>
  <Combobox variant="inputLike" />
  
  // After
  import { Button } from '@mastra/playground-ui';
  <Button size="icon-md"><Settings /></Button>
  <Button variant="default">…</Button>
  <Combobox variant="default" />

• Removed <Alert> in favor of <Notice>. The two components had significant visual and behavioral overlap; <Notice> is now the single banner primitive and supports every previous <Alert> use case. (#15791)

  <Notice> is also redesigned with a flatter API: title and icon are now props, each variant ships a default icon, an optional action prop renders a button aligned to the title, and a new note variant has been added alongside warning, destructive, info, and success. Theme tokens (notice-warning, notice-destructive, notice-info, notice-success, notice-note) replace the previous hardcoded colors.

  Migration

  // Before
  <Alert variant="warning">
    <AlertTitle>Provider not connected</AlertTitle>
    <AlertDescription as="p">Set the API key environment variable.</AlertDescription>
  </Alert>
  
  // After
  <Notice variant="warning" title="Provider not connected">
    <Notice.Message>Set the API key environment variable.</Notice.Message>
  </Notice>

Patch Changes

• Removed the "Avg Score" KPI card from the Metrics dashboard and the avg-score summary from the Scores card. (#15967)

• Fixed row click behavior in the dataset experiments compare view. Clicking a row while selection mode is active now toggles the row's selection instead of navigating to the experiment. Clicking directly on the checkbox no longer also triggers the row click handler. (#15492)

• Aligned AlertDialog visual styling with Dialog component for design system consistency. AlertDialog now uses the same surface tokens, border radius, shadow, animation curves, and typography scale as Dialog. The accessibility primitive remains separate (preserves role="alertdialog" and explicit Action/Cancel semantics) — only the visual shell was synced. Also added AlertDialog.Body for parity with Dialog. (#15988)

@mastra/react@0.2.33

Patch Changes

• Fixed suspended tool run IDs not being preserved after page refresh. (#15107)

@mastra/sentry@1.0.21

Patch Changes

• Renamed emitted OTel GenAI cache usage attributes to match the OpenTelemetry semantic conventions: (#15966)

  • gen_ai.usage.cached_input_tokens → gen_ai.usage.cache_read.input_tokens
  • gen_ai.usage.cache_write_tokens → gen_ai.usage.cache_creation.input_tokens

  gen_ai.usage.input_tokens is unchanged and remains the total prompt-token count. Cache attributes are emitted separately as subsets of that total.

  Updated Arize, Arthur, and Sentry mappings so cache values continue to flow through those exporters.

  Direct consumers should update any dashboards, alerts, or queries that reference the old attribute names.

@mastra/server@1.31.0

Patch Changes

• Fix GET /tools/:toolId and POST /tools/:toolId/execute to find dynamically-resolved agent tools (provided via toolsResolver / function-based tools) when they are not in the static tool registry. Errors thrown by an individual agent's listTools() during the lookup are now logged as warnings instead of being silently swallowed. (#13989)

• Fixed memory query validation when optional JSON query params are omitted with newer Zod versions. (#15969)

• Export MastraServerBase from @mastra/core/server so framework adapters that manage routing independently can share the same server base class. (#12751)

• Added platform channels framework with ChannelProvider interface, ChannelsStorage domain, and ChannelConnectResult discriminated union supporting OAuth, deep link, and immediate connection flows. Channels can be registered on the Mastra instance and expose connect/disconnect/list APIs for platform integrations. (#15876)

@mastra/slack@1.1.0

Minor Changes

• Added @mastra/slack channel integration for connecting AI agents to Slack workspaces. Provides automatic Slack app provisioning via OAuth, manifest management with drift detection, encrypted credential storage, slash command support, and threaded conversation handling. Usage: (#15876)

  import { SlackProvider } from '@mastra/slack';
  
  const mastra = new Mastra({
    channels: {
      slack: new SlackProvider({
        refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN!,
      }),
    },
  });
  
  // Connect an agent to Slack
  const result = await mastra.channels.slack.connect('my-agent');
  // result.type === 'oauth' → redirect user to result.authorizationUrl

Patch Changes

@mastra/voice-aws-nova-sonic@0.1.0

Minor Changes

• Add new @mastra/voice-aws-nova-sonic voice provider for AWS Bedrock Nova 2 Sonic. (#13232)

  The provider exposes a real-time bidirectional voice interface backed by the
  InvokeModelWithBidirectionalStreamCommand API on AWS Bedrock, including:

  • Live microphone streaming (send / listen) and assistant audio playback
    via speaking events
  • Live transcription via writing events with SPECULATIVE / FINAL
    generation stages
  • Barge-in / interrupt detection
  • Speaker selection across all 18 Nova Sonic voices and configurable
    endpointing sensitivity
  • Tool calling with per-session RequestContext
  • Configurable AWS region, model id, credentials (or default credential
    provider chain), and inference / turn-detection parameters

Patch Changes

Other updated packages

The following packages were updated with dependency changes only:

• @mastra/braintrust@1.0.22
• @mastra/datadog@1.0.22
• @mastra/deployer@1.31.0
• @mastra/deployer-cloud@1.31.0
• @mastra/deployer-cloudflare@1.1.30
• @mastra/deployer-netlify@1.1.6
• @mastra/deployer-vercel@1.1.24
• @mastra/express@1.3.16
• @mastra/hono@1.4.11
• @mastra/koa@1.4.16
• @mastra/laminar@1.0.21
• @mastra/langfuse@1.2.4
• @mastra/langsmith@1.1.19
• @mastra/longmemeval@1.0.35
• @mastra/mcp-docs-server@1.1.32
• @mastra/opencode@0.0.32
• @mastra/otel-bridge@1.0.21
• @mastra/posthog@1.0.22