mastra@1.1.0

Highlights

Unified Workspace API (Filesystem + Sandbox Execution + Search + Skills)

A new Workspace capability unifies agent-accessible filesystem operations, sandboxed command/code execution, keyword/semantic/hybrid search, and SKILL.md discovery with safety controls (read-only, approval flows, read-before-write guards). The Workspace is exposed end-to-end: core Workspace class (@mastra/core/workspace), server API endpoints (/workspaces/...), and new @mastra/client-js workspace client methods (files, skills, references, search).

Observability & Streaming Improvements (Trace Status, Better Spans, Tool Approval Tracing)

Tracing is more actionable: listTraces now returns a status (success|error|running), spans are cleaner (inherit entity metadata, remove internal spans, emit model chunk spans for all streaming chunks), and tool approval requests are visible in traces. Token accounting for Langfuse/PostHog is corrected (cached tokens separated) and default tracing tags are preserved across exporters.

Server Adapters: Serverless MCP Support + Explicit Route Auth Controls

Express/Fastify/Hono/Koa adapters gain mcpOptions (notably serverless: true) to run MCP HTTP transport statelessly in serverless/edge environments without overriding response handling. Adapters and @mastra/server also add explicit requiresAuth per route (defaulting to protected), improved custom-route auth enforcement (including path params), and corrected route prefix replacement/normalization.

requestContextSchema: Runtime-Validated, Type-Safe Request Context Everywhere

Tools, agents, workflows, and steps can now define a requestContextSchema (Zod) to validate required context at runtime and get typed access in execution; RequestContext.all provides convenient access to all validated values. This also flows into Studio UX (Request Context tab/forms) and fixes/improves propagation through agent networks and nested workflow execution for better observability and analytics.

Breaking Changes

Google embedding model router removes deprecated text-embedding-004; use google/gemini-embedding-001 instead.

Changelog

@mastra/core@1.1.0

dependencies updates:
- Updated dependency @isaacs/ttlcache@^2.1.4 ↗︎ (from ^1.4.1, in dependencies)

Fixes: #10184

Update provider registry and model documentation with latest models and providers

Fixes: 1cf5d2e

Fixed skill loading error caused by Zod version conflicts between v3 and v4. Replaced Zod schemas with plain TypeScript validation functions in skill metadata validation.

Fixes: #12485

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

The agent record now only stores metadata fields (id, status, activeVersionId, authorId, metadata, timestamps). All configuration fields (name, instructions, model, tools, etc.) live exclusively in version snapshot rows, enabling full version history and rollback.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Fix model router routing providers that use non-default AI SDK packages (e.g. @ai-sdk/anthropic, @ai-sdk/openai) to their correct SDK instead of falling back to openai-compatible. Add cerebras, togetherai, and deepinfra as native SDK providers.

Fixes: #12450

Make suspendedToolRunId nullable to fix the null issue in tool input validation

Fixes: #12303

Fixed agent.network() to properly pass requestContext to workflow runs. Workflow execution now includes user metadata (userId, resourceId) for observability and analytics. (Fixes #12330)

Fixes: #12379

Added dynamic agent management with CRUD operations and version tracking

New Features:

Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Fix ModelRouterLanguageModel to propagate supportedUrls from underlying model providers

Previously, ModelRouterLanguageModel (used when specifying models as strings like "mistral/mistral-large-latest" or "openai/gpt-4o") had supportedUrls hardcoded as an empty object. This caused Mastra to download all file URLs and convert them to bytes/base64, even when the model provider supports URLs natively.

This fix:

Changes supportedUrls to a lazy PromiseLike that resolves the underlying model's supported URL patterns
Updates llm-execution-step.ts to properly await supportedUrls when preparing messages

Impact:

Mistral: PDF URLs are now passed directly (fixes #12152)
OpenAI: Image URLs (and PDF URLs in response models) are now passed directly
Anthropic: Image URLs are now passed directly
Google: Files from Google endpoints are now passed directly

Note: Users who were relying on Mastra to download files from URLs that model providers cannot directly access (internal URLs, auth-protected URLs) may need to adjust their approach by either using base64-encoded content or ensuring URLs are publicly accessible to the model provider.

Fixes: #12167

Extended readOnly memory option to also apply to working memory. When readOnly: true, working memory data is provided as context but the updateWorkingMemory tool is not available.

Example:

// Working memory is loaded but agent cannot update it
const response = await agent.generate("What do you know about me?", {
  memory: {
    thread: "conversation-123",
    resource: "user-alice-456",
    options: { readOnly: true },
  },
});

Fixes: #12471

fix(core): skip non-serializable values in RequestContext.toJSON

Fixes: #12344

Added unified Workspace API for agent filesystem access, code execution, and search capabilities.

New Workspace class combines filesystem, sandbox, and search into a single interface that agents can use for file operations, command execution, and content search.

Key features:

Filesystem operations (read, write, copy, move, delete) through pluggable providers
Code and command execution in secure sandboxed environments with optional OS-level isolation
Keyword search, semantic search, and hybrid search modes
Skills system for discovering and using SKILL.md instruction files
Safety controls including read-before-write guards, approval flows, and read-only mode

Usage:

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  bm25: true,
});

const agent = new Agent({
  workspace,
  // Agent automatically receives workspace tools
});

Fixes: #11986

Fixed TypeScript error when calling bail() in workflow steps. bail() now accepts any value, so workflows can exit early with a custom result. Fixes #12424.

Fixes: #12429

Fixed type error when using createTool with Agent when exactOptionalPropertyTypes is enabled in TypeScript config. The ProviderDefinedTool structural type now correctly marks inputSchema as optional and allows execute to be undefined, matching the ToolAction interface.

Fixes: #12325

Fixed tracingOptions.tags not being preserved when merging defaultOptions with call-site options. Tags set in agent's defaultOptions.tracingOptions are now correctly passed to all observability exporters (Langfuse, Langsmith, Braintrust, Datadog, etc.). Fixes #12209.

Fixes: #12220

Added activeTools parameter support to model loop stream. The activeTools parameter can now be passed through the ModelLoopStreamArgs to control which tools are available during LLM execution.

Fixes: #12082

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

Fixed agent network crashing with 'Invalid task input' error when routing agent returns malformed JSON for tool/workflow prompts. The error is now fed back to the routing agent, allowing it to retry with valid JSON on the next iteration.

Fixes: #12477

Fixed type error when passing MastraVoice implementations (like OpenAIVoice) directly to Agent's voice config. Previously, the voice property only accepted CompositeVoice, requiring users to wrap their voice provider. Now you can pass any MastraVoice implementation directly.

Before (required wrapper):

const agent = new Agent({
  voice: new CompositeVoice({ output: new OpenAIVoice() }),
});

After (direct usage):

const agent = new Agent({
  voice: new OpenAIVoice(),
});

Fixes: #12329

Fixed output processors not being applied to messages saved during network execution. When using agent.network(), configured output processors (like TraceIdInjector for feedback attribution) are now correctly applied to all messages before they are saved to storage.

Fixes: #12346

Removed deprecated Google text-embedding-004 embedding model from the model router. Google shut down this model on January 14, 2026. Use google/gemini-embedding-001 instead.

Fixes: #12433

Fixed tool input validation failing when LLMs send null for optional fields (#12362). Zod's .optional() only accepts undefined, not null, causing validation errors with Gemini and other LLMs. Validation now retries with null values stripped when the initial attempt fails, so .optional() fields accept null while .nullable() fields continue to work correctly.

Fixes: #12396

Tracing fixes:
Spans now inherit entityType/entityId from the closest non-internal parent (#12250)
Processor spans correctly track separate input and output data
Model chunk spans are now emitted for all streaming chunks
Internal framework spans no longer appear in exported traces

Fixes: #12370

Fixed generated provider types so IDs starting with digits no longer break TypeScript builds

Fixes: #12418

Added RequestContext.all to access the entire RequestContext object values.

const { userId, featureFlags } = requestContext.all;

Added requestContextSchema support to tools, agents, workflows, and steps. Define a Zod schema to validate and type requestContext values at runtime.

Tool example:

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

const myTool = createTool({
  id: 'my-tool',
  inputSchema: z.object({ query: z.string() }),
  requestContextSchema: z.object({
    userId: z.string(),
    apiKey: z.string(),
  }),
  execute: async (input, context) => {
    // context.requestContext is typed as RequestContext<{ userId: string, apiKey: string }>
    const userId = context.requestContext?.get('userId');
    return { result: 'success' };
  },
});

Agent example:

import { Agent } from '@mastra/core/agent';
import { z } from 'zod';

const agent = new Agent({
  name: 'my-agent',
  model: openai('gpt-4o'),
  requestContextSchema: z.object({
    userId: z.string(),
    featureFlags: z.object({
      debugMode: z.boolean().optional(),
      enableSearch: z.boolean().optional(),
    }).optional(),
  }),
  instructions: ({ requestContext }) => {
    // Access validated context values with type safety
    const { userId, featureFlags } = requestContext.all;

    const baseInstructions = `You are a helpful assistant. The current user ID is: ${userId}.`;

    if (featureFlags?.debugMode) {
      return `${baseInstructions} Debug mode is enabled - provide verbose responses.`;
    }

    return baseInstructions;
  },
  tools: ({ requestContext }) => {
    const tools: Record<string, any> = {
      weatherInfo,
    };

    // Conditionally add tools based on validated feature flags
    const { featureFlags } = requestContext.all;
    if (featureFlags?.enableSearch) {
      tools['web_search_preview'] = openai.tools.webSearchPreview();
    }

    return tools;
  },
});

Workflow example:

import { createWorkflow } from '@mastra/core/workflows';
import { z } from 'zod';

const workflow = createWorkflow({
  id: 'my-workflow',
  inputSchema: z.object({ data: z.string() }),
  requestContextSchema: z.object({
    tenantId: z.string(),
  }),
});

const step = createStep({
  id: 'my-step',
  description: 'My step description',
  inputSchema: z.object({ data: z.string() }),
  outputSchema: z.object({ result: z.string() }),
  requestContextSchema: z.object({
    userId: z.string(),
  }),
  execute: async ({ inputData, requestContext }) => {
    const userId = requestContext?.get('userId');
    return {
      result: 'some result here',
    };
  },
});

workflow.then(step).commit()

When requestContextSchema is defined, validation runs automatically and throws an error if required context values are missing or invalid.

Fixes: #12259

Fixed network mode not applying user-configured input/output processors (like token limiters) to the routing agent. This caused unbounded context growth during network iterations.

User-configured processors are now correctly passed to the routing agent, while memory-derived processors (which could interfere with routing logic) are excluded.

Fixes: #12074

Fixed repeated build failures caused by stale global cache (~/.cache/mastra/) containing invalid TypeScript in provider-types.generated.d.ts. Provider names starting with digits (e.g. 302ai) are now properly quoted, and the global cache sync validates .d.ts files before copying to prevent corrupted files from overwriting correct ones.

Fixes: #12425

Update @isaacs/ttlcache to v2 and fix import for v2 compatibility (changed from default to named export)

Fixes: #10184

Fixed custom data parts from writer.custom() breaking subsequent messages with Gemini. Messages containing only data-* parts no longer produce empty content arrays that cause Gemini to fail with 'must include at least one parts field'.

Fixes: #12373

Improve autoresume prompt sent to LLM to ensure gemini resumes well. Gemini sometimes doesn't use the previous messages to create inputData for the tool to resume, the prompt was updated to make sure it gets the inputData from the suspended tool call.

Fixes: #12320

Fixed sub-agents in Agent Networks seeing completion-check feedback from prior iterations, so delegated agents stay focused on their task.

Fixes: #12338

Fix TypeScript types for custom API route handlers to include requestContext in Hono context Variables. Previously, only mastra was typed, causing TypeScript errors when accessing c.get('requestContext') even though the runtime correctly provided this context.

Fixes: #12419

Let callers cancel a running agent network call and handle abort callbacks.

Example Before:

const stream = await agent.network(task);

After:

const controller = new AbortController();
const stream = await agent.network(task, {
  abortSignal: controller.signal,
  onAbort: ({ primitiveType, primitiveId }) => {
    logger.info(`Aborted ${primitiveType}:${primitiveId}`);
  },
});

controller.abort();

Related issue: #12282

Fixes: #12351

@internal/playground@1.1.0

Fix link to evals documentation

Fixes: #12122

Fixed the swagger-ui link to use a relative path instead of localhost.

Fixes: #12120

@mastra/agent-builder@1.0.1

Fixed file naming conversion when merging templates. Kebab-case filenames like csv-to-questions-workflow.ts were incorrectly converted to all-lowercase (csvtoquestionsworkflow.ts) instead of proper camelCase (csvToQuestionsWorkflow.ts). PascalCase and acronym-boundary conversions are also fixed.

Fixes: #12436

Fixed latent Memory storage bug in AgentBuilder. AgentBuilder was created without providing storage to Memory, causing intermittent failures when Memory operations were invoked. Now uses InMemoryStore as a fallback when no storage is provided, allowing it to function without explicit storage configuration.

Fixes: #12347

@mastra/ai-sdk@1.0.3

fix(ai-sdk): import ReadableStream and TransformStream from node:stream/web to fix TypeScript async iterator errors

Fixed TypeScript build errors when using toAISdkStream() with for await...of loops. The function now explicitly imports ReadableStream and TransformStream from 'node:stream/web', ensuring the Node.js types (which include Symbol.asyncIterator support) are used instead of global types that may not have async iterator support in all TypeScript configurations.

This resolves issue #11884 where users encountered the error: "Type 'ReadableStream<InferUIMessageChunk<UIMessage>>' must have a 'Symbol.asyncIterator' method that returns an async iterator."

Fixes: #12159

@mastra/arize@1.0.1

dependencies updates:
- Updated dependency @arizeai/openinference-genai@0.1.5 ↗︎ (from 0.1.0, in dependencies)

Fixes: #12146

dependencies updates:
- Updated dependency @arizeai/openinference-semantic-conventions@^2.1.7 ↗︎ (from ^2.1.2, in dependencies)

Fixes: #12147

Fixed incorrect span kind mapping in @mastra/arize. Workflow spans now correctly map to CHAIN, agent spans to AGENT, and tool spans to TOOL instead of defaulting to LLM.

Fixes: #12423

@mastra/clickhouse@1.1.0

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

@mastra/client-js@1.1.0

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Added workspace client methods for interacting with workspace API endpoints.

New methods on MastraClient:

listWorkspaces() - List all available workspaces
getWorkspace(workspaceId) - Get a workspace client for a specific workspace
workspace.info() - Get workspace info and capabilities
workspace.listFiles() / readFile() / writeFile() / delete() / mkdir() / stat() - Filesystem operations
workspace.listSkills() / getSkill(name).details() / .listReferences() / .getReference() - Skill management
workspace.search() - Search indexed content

Usage:

import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:4111' });

// List workspaces and get the first one
const { workspaces } = await client.listWorkspaces();
const workspace = client.getWorkspace(workspaces[0].id);

// Read a file
const { content } = await workspace.readFile('/docs/guide.md');

// List skills
const { skills } = await workspace.listSkills();

// Get skill details
const skill = workspace.getSkill('my-skill');
const details = await skill.details();

// Search content
const { results } = await workspace.search({ query: 'authentication', mode: 'hybrid' });

Fixes: #11986

Added requestContextSchema type support.

Fixes: #12259

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Added apiPrefix option to MastraClient for connecting to servers with custom API route prefixes.

Before: The client always used the /api prefix for all endpoints.

After: You can now specify a custom prefix when deploying Mastra behind non-default paths:

const client = new MastraClient({
  baseUrl: 'http://localhost:3000',
  apiPrefix: '/mastra', // Calls /mastra/agents, /mastra/workflows, etc.
});

The default remains /api for backward compatibility. See #12261 for more details.

Fixes: #12295

Stored agent edits no longer fail silently. PATCH requests now save changes correctly.

Fixes: #12504

Fix PATCH request JSON-body handling in @mastra/client-js so stored agent edit flows work correctly. Fix stored agent schema migration in @mastra/libsql and @mastra/pg to drop and recreate the versions table when the old snapshot-based schema is detected, clean up stale draft records from partial create failures, and remove lingering legacy tables. Restores create and edit flows for stored agents.

Fixes: #12504

@mastra/cloudflare@1.1.0

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

@mastra/codemod@1.0.1

dependencies updates:
- Updated dependency @clack/prompts@1.0.0-alpha.9 ↗︎ (from 1.0.0-alpha.6, in dependencies)

Fixes: #11584

Added workflow-get-init-data codemod that transforms getInitData() calls to getInitData<any>().

This codemod helps migrate code after the getInitData return type changed from any to unknown. Adding the explicit <any> type parameter restores the previous behavior while maintaining type safety.

Usage:

npx @mastra/codemod@latest v1/workflow-get-init-data .

Before:

createStep({
  execute: async ({ getInitData }) => {
    const initData = getInitData();
    if (initData.key === 'value') {}
  },
});

After:

createStep({
  execute: async ({ getInitData }) => {
    const initData = getInitData<any>();
    if (initData.key === 'value') {}
  },
});

Fixes: #12212

@mastra/convex@1.0.1

Fixed Convex schema validation error where mastra_workflow_snapshots index by_record_id referenced a missing id field. The id field is now explicitly defined in the Convex workflow snapshots table schema. This enables successful npx convex dev deployments that were previously failing with SchemaDefinitionError.

Fixes: #12319

@mastra/deployer@1.1.0

dependencies updates:
- Updated dependency @babel/core@^7.28.6 ↗︎ (from ^7.28.5, in dependencies)

Fixes: #12191

dependencies updates:
- Updated dependency rollup@~4.55.1 ↗︎ (from ~4.50.2, in dependencies)

Fixes: #9737

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Fixed lint errors in deployer package

Fixes: #12476

Fixed swagger-ui to use the correct OpenAPI endpoint URL (/api/openapi.json).

Fixes: #11786

Fixed dependency version resolution in monorepos.

What's fixed:

Dependency versions are now accurately resolved in monorepos, even with hoisted dependencies
ESM-only packages and transitive workspace dependencies are now correctly handled
Deployer-provided packages (like hono) that aren't in your project are now resolved correctly

Why this happened:

Previously, dependency versions were resolved at bundle time without the correct project context, causing the bundler to fall back to latest instead of using the actual installed version.

Fixes: #12125

@mastra/deployer-cloudflare@1.0.2

dependencies updates:
- Updated dependency @babel/core@^7.28.6 ↗︎ (from ^7.28.5, in dependencies)

Fixes: #12191

dependencies updates:
- Updated dependency rollup@~4.55.1 ↗︎ (from ~4.50.2, in dependencies)

Fixes: #9737

Fixed Cloudflare Workers exceeding the 3MB size limit due to TypeScript being bundled. The deployer now stubs out TypeScript (~10MB) since the agent-builder gracefully falls back to basic validation when it's unavailable.

Fixes: #12420

@mastra/evals@1.0.1

Force alpha version bump for @mastra/evals, @mastra/loggers, @mastra/observability, and @mastra/memory

Fixes: #12505

@mastra/express@1.1.0

Added explicit auth control to built-in API routes. All routes now have a requiresAuth property that determines whether authentication is required. This eliminates route matching overhead and makes auth requirements clear in route definitions. Routes default to requiresAuth: true (protected) for security. To make a route public, set requiresAuth: false in the route definition.

Fixes: #12153

Fixed authentication bypass for custom routes in dev mode. Routes registered with registerApiRoute and requiresAuth: true now correctly enforce authentication even when MASTRA_DEV=true.

Fixes: #12339

Added mcpOptions to server adapters for serverless MCP support.

Why: MCP HTTP transport uses session management by default, which requires persistent state across requests. This doesn't work in serverless environments like Cloudflare Workers or Vercel Edge where each request runs in isolation. The new mcpOptions parameter lets you enable stateless mode without overriding the entire sendResponse() method.

Before:

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

After:

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

Fixes: #12324

Fixed route prefix behavior to correctly replace the default /api prefix instead of prepending to it. Previously, setting prefix: '/api/v2' resulted in routes at /api/v2/api/agents. Now routes correctly appear at /api/v2/agents as documented.

Fixes: #12221

@mastra/fastify@1.1.0

Added explicit auth control to built-in API routes. All routes now have a requiresAuth property that determines whether authentication is required. This eliminates route matching overhead and makes auth requirements clear in route definitions. Routes default to requiresAuth: true (protected) for security. To make a route public, set requiresAuth: false in the route definition.

Fixes: #12153

Fixed authentication bypass for custom routes in dev mode. Routes registered with registerApiRoute and requiresAuth: true now correctly enforce authentication even when MASTRA_DEV=true.

Fixes: #12339

Added mcpOptions to server adapters for serverless MCP support.

Before:

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

After:

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

Fixes: #12324

Fixed route prefix behavior to correctly replace the default /api prefix instead of prepending to it. Previously, setting prefix: '/api/v2' resulted in routes at /api/v2/api/agents. Now routes correctly appear at /api/v2/agents as documented.

Fixes: #12221

@mastra/google-cloud-pubsub@1.0.1

dependencies updates:
- Updated dependency @google-cloud/pubsub@^5.2.2 ↗︎ (from ^5.2.0, in dependencies)

Fixes: #12265

@mastra/hono@1.1.0

Added explicit auth control to built-in API routes. All routes now have a requiresAuth property that determines whether authentication is required. This eliminates route matching overhead and makes auth requirements clear in route definitions. Routes default to requiresAuth: true (protected) for security. To make a route public, set requiresAuth: false in the route definition.

Fixes: #12153

Fixed authentication bypass for custom routes in dev mode. Routes registered with registerApiRoute and requiresAuth: true now correctly enforce authentication even when MASTRA_DEV=true.

Fixes: #12339

Fixed malformed JSON body handling in Hono adapter. When a POST request contains invalid JSON (e.g., missing closing braces), the server now returns HTTP 400 Bad Request with a structured error message instead of silently accepting the request with HTTP 200. This prevents workflows from starting with undefined input data. (#12310)

Fixes: #12332

Added mcpOptions to server adapters for serverless MCP support.

Before:

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

After:

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

Fixes: #12324

Fixed route prefix behavior to correctly replace the default /api prefix instead of prepending to it. Previously, setting prefix: '/api/v2' resulted in routes at /api/v2/api/agents. Now routes correctly appear at /api/v2/agents as documented.

Fixes: #12221

@mastra/inngest@1.0.1

Added requestContextSchema type support.

Fixes: #12259

@mastra/koa@1.1.0

Added explicit auth control to built-in API routes. All routes now have a requiresAuth property that determines whether authentication is required. This eliminates route matching overhead and makes auth requirements clear in route definitions. Routes default to requiresAuth: true (protected) for security. To make a route public, set requiresAuth: false in the route definition.

Fixes: #12153

Fixed authentication bypass for custom routes in dev mode. Routes registered with registerApiRoute and requiresAuth: true now correctly enforce authentication even when MASTRA_DEV=true.

Fixes: #12339

Added mcpOptions to server adapters for serverless MCP support.

Before:

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

After:

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

Fixes: #12324

Fixed route prefix behavior to correctly replace the default /api prefix instead of prepending to it. Previously, setting prefix: '/api/v2' resulted in routes at /api/v2/api/agents. Now routes correctly appear at /api/v2/agents as documented.

Fixes: #12221

@mastra/langfuse@1.0.1

Fixed token usage reporting for Langfuse and PostHog exporters. The input token count now correctly excludes cached tokens, matching each platform's expected format for accurate cost calculation. Cache read and cache write tokens are now properly reported as separate fields (cache_read_input_tokens, cache_creation_input_tokens) rather than being included in the base input count. Added defensive clamping to ensure input tokens never go negative if cache values exceed the total.

Fixes: #12465

@mastra/libsql@1.1.0

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

Stored agent edits no longer fail silently. PATCH requests now save changes correctly.

Fixes: #12504

Fix PATCH request JSON-body handling in @mastra/client-js so stored agent edit flows work correctly. Fix stored agent schema migration in @mastra/libsql and @mastra/pg to drop and recreate the versions table when the old snapshot-based schema is detected, clean up stale draft records from partial create failures, and remove lingering legacy tables. Restores create and edit flows for stored agents.

Fixes: #12504

@mastra/loggers@1.0.1

Force alpha version bump for @mastra/evals, @mastra/loggers, @mastra/observability, and @mastra/memory

Fixes: #12505

@mastra/memory@1.0.1

Force alpha version bump for @mastra/evals, @mastra/loggers, @mastra/observability, and @mastra/memory

Fixes: #12505

Extended readOnly memory option to also apply to working memory. When readOnly: true, working memory data is provided as context but the updateWorkingMemory tool is not available.

Example:

// Working memory is loaded but agent cannot update it
const response = await agent.generate("What do you know about me?", {
  memory: {
    thread: "conversation-123",
    resource: "user-alice-456",
    options: { readOnly: true },
  },
});

Fixes: #12471

@mastra/mongodb@1.1.0

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

@mastra/mssql@1.1.0

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

@mastra/observability@1.1.0

Force alpha version bump for @mastra/evals, @mastra/loggers, @mastra/observability, and @mastra/memory

Fixes: #12505

Fixed tracingOptions.tags not being preserved when merging defaultOptions with call-site options. Tags set in agent's defaultOptions.tracingOptions are now correctly passed to all observability exporters (Langfuse, Langsmith, Braintrust, Datadog, etc.). Fixes #12209.

Fixes: #12220

Requires @mastra/core 1.0.5 or later. If upgrading, ensure your @mastra/core package is also updated.

Fixes: #12370

Tracing fixes:
Spans now inherit entityType/entityId from the closest non-internal parent (#12250)
Processor spans correctly track separate input and output data
Model chunk spans are now emitted for all streaming chunks
Internal framework spans no longer appear in exported traces

Fixes: #12370

Add tool approval tracing to spans for debugging

Added the ability to see tool approval requests in traces for debugging purposes. When a tool requires approval, a MODEL_CHUNK span named chunk: 'tool-call-approval' is now created containing:

The tool call ID and name for identification
The arguments that need approval
The resume schema defining the approval response format

This enables users to debug their system by seeing approval requests in traces, making it easier to understand the flow of tool approvals and their payloads.

Fixes: #12171

@mastra/pg@1.1.0

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Added status field to listTraces response. The status field indicates the trace state: success (completed without error), error (has error), or running (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the error and endedAt fields.

Fixes: #12213

Stored agent edits no longer fail silently. PATCH requests now save changes correctly.

Fixes: #12504

Fix PATCH request JSON-body handling in @mastra/client-js so stored agent edit flows work correctly. Fix stored agent schema migration in @mastra/libsql and @mastra/pg to drop and recreate the versions table when the old snapshot-based schema is detected, clean up stale draft records from partial create failures, and remove lingering legacy tables. Restores create and edit flows for stored agents.

Fixes: #12504

@mastra/playground-ui@8.0.0

Fix link to evals documentation

Fixes: #12122

Added ghost variant support to domain comboboxes (AgentCombobox, WorkflowCombobox, MCPServerCombobox, ScorerCombobox, ToolCombobox) and moved them into the breadcrumb for a cleaner navigation pattern

Fixes: #12357

Added processor combobox to processor page header for quick navigation between processors

Fixes: #12368

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Moved model provider and model selection dropdowns from the agent side panel to the chat composer area for easier access during conversations

Fixes: #12407

Added Request Context tab to Tools, Agents, and Workflows in Mastra Studio. When an entity defines a requestContextSchema, a form is displayed allowing you to input context values before execution.

Fixes: #12259

Fixed keyboard events in command palette propagating to underlying page elements like tables

Fixes: #12458

Refactored Combobox component to use @base-ui/react instead of custom Radix UI Popover implementation. This removes ~70 lines of manual keyboard navigation code while preserving the same props interface and styling.

Fixes: #12377

fix workflow run input caching bug in studio UI

Fixes: #11784

Refactored agent model dropdowns to use the Combobox design system component, reducing code complexity while preserving all features including custom model ID support and provider connection status indicators.

Fixes: #12367

Fixed model combobox auto-opening on mount. The model selector now only opens when explicitly changing providers, improving the initial page load experience.

Fixes: #12456

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Fixed legacy agent runs so each request now gets a unique run ID, improving trace readability in observability tools.

Fixes: #12229

Improved skill activation styling with cleaner badge appearance and dark-themed tooltip on hover.

Fixes: #12487

Added workflow run ID to breadcrumbs with truncation and copy functionality

Fixes: #12409

Added Command component (CMDK) with CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, and CommandShortcut subcomponents for building command palettes and searchable menus

Fixes: #12360

Refactored WorkflowTrigger component into focused sub-components for better maintainability. Extracted WorkflowTriggerForm, WorkflowSuspendedSteps, WorkflowCancelButton, and WorkflowStepsStatus. Added useSuspendedSteps and useWorkflowSchemas hooks for memoized computations. No changes to public API.

Fixes: #12349

Bump playground-ui to v7.1.0

Fixes: #12186

Added keyboard navigation support to Table component with new useTableKeyboardNavigation hook and isActive prop on Row

Fixes: #12352

Use useExecuteWorkflow hook from @mastra/react instead of local implementation in playground-ui

Fixes: #12138

Refined color palette for a more polished dark theme. Surfaces now use warm near-blacks, accents are softer and less neon, borders are subtle white overlays for a modern look.

Fixes: #12350

Added useCancelWorkflowRun hook to @mastra/react for canceling workflow runs. This hook was previously only available internally in playground-ui and is now exported for use in custom applications.

Fixes: #12142

Added global command palette (Cmd+K) for quick navigation to any entity in Mastra Studio. Press Cmd+K (or Ctrl+K on Windows/Linux) to search and navigate to agents, workflows, tools, scorers, processors, and MCP servers.

Fixes: #12360

Fixed skill detail page crashing when skills have object-typed compatibility or metadata fields. Skills from skills.sh and other external sources now display correctly.

Fixes: #12491

Remove hardcoded temperature: 0.5 and topP: 1 defaults from playground agent settings Let agent config and provider defaults handle these values instead

Fixes: #12256

Added useStreamWorkflow hook to @mastra/react for streaming workflow execution. This hook supports streaming, observing, resuming, and time-traveling workflows. It accepts tracingOptions and onError as parameters for better customization.

Fixes: #12151

Improved command palette with sidebar toggle, direct links to agent/workflow traces, and preserved search result ordering

Fixes: #12406

Added view transitions to internal sidebar navigation links for smoother page transitions

Fixes: #12358

Added raw SKILL.md source view in skill detail page. The 'Source' toggle now shows the full file contents including YAML frontmatter.

Fixes: #12497

Added workspace UI components for the Mastra playground.

New components:

FileBrowser - Browse and manage workspace files with breadcrumb navigation
FileViewer - View file contents with syntax highlighting
SkillsTable - List and search available skills
SkillDetail - View skill details, instructions, and references
SearchPanel - Search workspace content with BM25/vector/hybrid modes
ReferenceViewerDialog - View skill reference file contents

Usage:

import { FileBrowser, FileViewer, SkillsTable } from '@mastra/playground-ui';

// File browser with navigation
<FileBrowser
  entries={files}
  currentPath="/docs"
  onNavigate={setPath}
  onFileSelect={handleFileSelect}
/>

// Skills table with search
<SkillsTable
  skills={skills}
  onSkillSelect={handleSkillSelect}
/>

Fixes: #11986

Added IconButton design system component that combines button styling with built-in tooltip support. Replaced TooltipIconButton with IconButton throughout the chat interface for consistency.

Fixes: #12410

Developers can now configure a custom API route prefix in the Studio UI, enabling Studio to work with servers using custom base paths (e.g., /mastra instead of the default /api). See #12261 for more details.

Fixes: #12295

@mastra/posthog@1.0.1

Fixed token usage reporting for Langfuse and PostHog exporters. The input token count now correctly excludes cached tokens, matching each platform's expected format for accurate cost calculation. Cache read and cache write tokens are now properly reported as separate fields (cache_read_input_tokens, cache_creation_input_tokens) rather than being included in the base input count. Added defensive clamping to ensure input tokens never go negative if cache values exceed the total.

Fixes: #12465

@mastra/rag@2.1.0

Added support for 20 additional languages in code chunking

Extended RecursiveCharacterTransformer to support all languages defined in the Language enum. Previously, only 6 languages were supported (CPP, C, TS, MARKDOWN, LATEX, PHP), causing runtime errors for other defined languages.

Newly supported languages:

GO, JAVA, KOTLIN, JS, PYTHON, RUBY, RUST, SCALA, SWIFT (popular programming languages)
HTML, SOL (Solidity), CSHARP, COBOL, LUA, PERL, HASKELL, ELIXIR, POWERSHELL (additional languages)
PROTO (Protocol Buffers), RST (reStructuredText) (data/documentation formats)

Each language has been configured with appropriate separators based on its syntax patterns (modules, classes, functions, control structures) to enable semantic code chunking.

Before:

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

// These would all throw "Language X is not supported!" errors
const goTransformer = RecursiveCharacterTransformer.fromLanguage(Language.GO);
const pythonTransformer = RecursiveCharacterTransformer.fromLanguage(Language.PYTHON);
const rustTransformer = RecursiveCharacterTransformer.fromLanguage(Language.RUST);

After:

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

// All languages now work seamlessly
const goTransformer = RecursiveCharacterTransformer.fromLanguage(Language.GO);
const goChunks = goTransformer.transform(goCodeDocument);

const pythonTransformer = RecursiveCharacterTransformer.fromLanguage(Language.PYTHON);
const pythonChunks = pythonTransformer.transform(pythonCodeDocument);

const rustTransformer = RecursiveCharacterTransformer.fromLanguage(Language.RUST);
const rustChunks = rustTransformer.transform(rustCodeDocument);
// All languages in the Language enum are now fully supported

Fixes: #12154

Add support for PHP in Language enum

Previously, the Language enum defined PHP, but it was not supported in the getSeparatorsForLanguage method. This caused runtime errors when trying to use PHP for code chunking.

This change adds proper separator definitions for PHP, ensuring that PHP defined in the Language enum is now fully supported. PHP has been configured with appropriate separators based on its syntax and common programming patterns (classes, functions, control structures, etc.).

Before:

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

const transformer = RecursiveCharacterTransformer.fromLanguage(Language.PHP);
const chunks = transformer.transform(phpCodeDocument);
// Throws: "Language PHP is not supported!"

After:

import { RecursiveCharacterTransformer, Language } from '@mastra/rag';

const transformer = RecursiveCharacterTransformer.fromLanguage(Language.PHP);
const chunks = transformer.transform(phpCodeDocument);
// Successfully chunks PHP code at namespace, class, function boundaries

Fixes the issue where using Language.PHP would throw "Language PHP is not supported!" error.

Fixes: #12124

@mastra/react@0.2.0

Added apiPrefix prop to MastraClientProvider for connecting to servers with custom API route prefixes (defaults to /api).

Default usage (no change required):

<MastraClientProvider baseUrl="http://localhost:3000">
  {children}
</MastraClientProvider>

Custom prefix usage:

<MastraClientProvider baseUrl="http://localhost:3000" apiPrefix="/mastra">
  {children}
</MastraClientProvider>

See #12261 for more details.

Fixes: #12295

Use useExecuteWorkflow hook from @mastra/react instead of local implementation in playground-ui

Fixes: #12138

Added useCancelWorkflowRun hook to @mastra/react for canceling workflow runs. This hook was previously only available internally in playground-ui and is now exported for use in custom applications.

Fixes: #12142

Added useStreamWorkflow hook to @mastra/react for streaming workflow execution. This hook supports streaming, observing, resuming, and time-traveling workflows. It accepts tracingOptions and onError as parameters for better customization.

Fixes: #12151

@mastra/server@1.1.0

Restructured stored agents to use a thin metadata record with versioned configuration snapshots.

Key changes:

Stored Agent records are now thin metadata-only (StorageAgentType)
All config lives in version snapshots (StorageAgentSnapshotType)
New resolved type (StorageResolvedAgentType) merges agent record + active version config
Renamed ownerId to authorId for multi-tenant filtering
Changed memory field type from string to Record<string, unknown>
Added status field ('draft' | 'published') to agent records
Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
List endpoints return resolved agents (thin record + active version config)
Auto-versioning on update with retention limits and race condition handling

Fixes: #12488

Fixed server handlers to find stored and sub-agents, not just registered agents. Agents created via the API or stored in the database are now correctly resolved in A2A, memory, scores, tools, and voice endpoints.

Fixes: #12481

Added explicit auth control to built-in API routes. All routes now have a requiresAuth property that determines whether authentication is required. This eliminates route matching overhead and makes auth requirements clear in route definitions. Routes default to requiresAuth: true (protected) for security. To make a route public, set requiresAuth: false in the route definition.

Fixes: #12153

Fixed a bug introduced in PR #12251 where requestContext was not passed through to agent and workflow operations. This could cause tools and nested operations that rely on requestContext values to fail or behave incorrectly.

Fixes: #12428

Fix broken import for deepEqual by inlining the function into server.

Fixes: #12446

Added requestContextSchema type support.

Fixes: #12259

Fixed authentication bypass for custom routes in dev mode. Routes registered with registerApiRoute and requiresAuth: true now correctly enforce authentication even when MASTRA_DEV=true.

Fixes: #12339

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Fixed malformed JSON body handling in Hono adapter. When a POST request contains invalid JSON (e.g., missing closing braces), the server now returns HTTP 400 Bad Request with a structured error message instead of silently accepting the request with HTTP 200. This prevents workflows from starting with undefined input data. (#12310)

Fixes: #12332

Fix path parameter routes not respecting requiresAuth setting

Fixes issue where custom API routes with path parameters (e.g., /users/:id) were incorrectly requiring authentication even when requiresAuth was set to false. The authentication middleware now uses pattern matching to correctly match dynamic routes against registered patterns.

Changes:

Inlined path pattern matching utility (based on regexparam) to avoid dependency complexity
Updated isCustomRoutePublic() to iterate through routes and match path patterns
Enhanced pathMatchesPattern() to support path parameters (:id), optional parameters (:id?), and wildcards (*)
Added comprehensive test coverage for path parameter matching scenarios

Fixes: #12143

Improves CommonJS support by adding typefiles to the root directory

Fixes: #12068

Added mcpOptions to server adapters for serverless MCP support.

Before:

const server = new MastraServer({
  app,
  mastra,
});
// No way to pass serverless option to MCP HTTP transport

After:

const server = new MastraServer({
  app,
  mastra,
  mcpOptions: {
    serverless: true,
  },
});
// MCP HTTP transport now runs in stateless mode

Fixes: #12324

Fixed memory API endpoints to respect MASTRA_RESOURCE_ID_KEY and MASTRA_THREAD_ID_KEY from middleware. Previously, these endpoints ignored the reserved context keys and used client-provided values directly, allowing authenticated users to potentially access other users' threads and messages. Now when middleware sets these reserved keys, they take precedence over client-provided values for secure user isolation.

Fixes: #12251

Added support for including custom API routes in the generated OpenAPI documentation. Custom routes registered via registerApiRoute() now appear in the OpenAPI spec alongside built-in Mastra routes.

Fixes: #11786

Added workspace API endpoints for filesystem operations, skill management, and content search.

New endpoints:

GET /workspaces - List all workspaces (from Mastra instance and agents)
GET /workspaces/:workspaceId - Get workspace info and capabilities
GET/POST/DELETE /workspaces/:workspaceId/fs/* - Filesystem operations (read, write, list, delete, mkdir, stat)
GET /workspaces/:workspaceId/skills - List available skills
GET /workspaces/:workspaceId/skills/:skillName - Get skill details
GET /workspaces/:workspaceId/skills/:skillName/references - List skill references
GET /workspaces/:workspaceId/search - Search indexed content

Usage:

// List workspaces
const { workspaces } = await fetch('/api/workspaces').then(r => r.json());
const workspaceId = workspaces[0].id;

// Read a file
const response = await fetch(`/api/workspaces/${workspaceId}/fs/read?path=/docs/guide.md`);
const { content } = await response.json();

// List skills
const skills = await fetch(`/api/workspaces/${workspaceId}/skills`).then(r => r.json());

// Search content
const results = await fetch(`/api/workspaces/${workspaceId}/search?query=authentication&mode=hybrid`)
  .then(r => r.json());

Fixes: #11986

Route prefixes are now normalized for consistent handling (trailing slashes removed, leading slashes added, multiple slashes collapsed).

Fixes: #12295

Fixed route prefix behavior to correctly replace the default /api prefix instead of prepending to it. Previously, setting prefix: '/api/v2' resulted in routes at /api/v2/api/agents. Now routes correctly appear at /api/v2/agents as documented.

Fixes: #12221

@mastra/voice-google-gemini-live@0.11.1

dependencies updates:
- Updated dependency ws@^8.19.0 ↗︎ (from ^8.18.3, in dependencies)

Fixes: #11645

@mastra/voice-openai-realtime@0.12.1

dependencies updates:
- Updated dependency ws@^8.19.0 ↗︎ (from ^8.18.3, in dependencies)

Fixes: #11645

create-mastra@1.1.0

fix workflow run input caching bug in studio UI

Fixes: #11784

Fixed Studio CLI placeholder replacement so generated URLs are valid.

Fixes: #12108

Fixed peer dependency checker to correctly validate prerelease versions (e.g., 1.1.0-alpha.1 now satisfies >=1.0.0-0 <2.0.0-0)

Fixes: #12495

Added peer dependency version validation when running mastra dev and mastra build. The CLI now checks if installed @mastra/* packages satisfy each other's peer dependency requirements and displays a warning with upgrade instructions when mismatches are detected.

Fixes: #12469

Improved peer dependency version mismatch warnings in the CLI:
When the dev server crashes with an error, a hint is now shown suggesting that updating mismatched packages may fix the issue
The update command now uses the correct package manager (pnpm/npm/yarn) detected from lockfiles
The update command uses add @package@latest instead of update to ensure major version updates are applied
Added MASTRA_SKIP_PEERDEP_CHECK=1 environment variable to skip the peer dependency check

Fixes: #12479

fix workflow run input caching bug in studio UI

Fixes: #11784

Added dynamic agent management with CRUD operations and version tracking

New Features:

Create, edit, and delete agents directly from the Mastra Studio UI
Full version history for agents with compare and restore capabilities
Visual diff viewer to compare agent configurations across versions
Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
AI-powered instruction enhancement

Storage:

New storage interfaces for stored agents and agent versions
PostgreSQL, LibSQL, and MongoDB implementations included
In-memory storage for development and testing

API:

RESTful endpoints for agent CRUD operations
Version management endpoints (create, list, activate, restore, delete, compare)
Automatic versioning on agent updates when enabled

Client SDK:

JavaScript client with full support for stored agents and versions
Type-safe methods for all CRUD and version operations

Usage Example:

// Server-side: Configure storage
import { Mastra } from '@mastra/core';
import { PgAgentsStorage } from '@mastra/pg';

const mastra = new Mastra({
  agents: { agentOne },
  storage: {
    agents: new PgAgentsStorage({
      connectionString: process.env.DATABASE_URL,
    }),
  },
});

// Client-side: Use the SDK
import { MastraClient } from '@mastra/client-js';

const client = new MastraClient({ baseUrl: 'http://localhost:3000' });

// Create a stored agent
const agent = await client.createStoredAgent({
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
  instructions: 'You are a helpful customer support agent...',
  tools: ['search', 'email'],
});

// Create a version snapshot
await client.storedAgent(agent.id).createVersion({
  name: 'v1.0 - Initial release',
  changeMessage: 'First production version',
});

// Compare versions
const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');

Why: This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.

Fixes: #12038

Fixed Studio scorers page crash when navigating directly to a scorer URL or reloading the page. The page would crash with 'Cannot read properties of undefined' due to a race condition between scorer and agents data loading.

Fixes: #12126

Added --server-api-prefix option to mastra studio command for connecting to servers with custom API route prefixes.

# Connect to server using custom prefix
mastra studio --server-port 3000 --server-api-prefix /mastra

Fixes: #12295