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>' 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.

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

• 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.

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/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.

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/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.

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/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.

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

• 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.

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

• 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.

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

• 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.

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

• 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.

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

• 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.

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 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

mastra@1.1.0

• 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