Mastra now supports relationship-based, resource-level authorization with centralized enforcement before agent runs (generate()/stream()), tool/workflow execution, and memory thread access via new IFGAProvider/IFGAManager + checkFGA()/FGADeniedError. FGA is also enforced consistently in @mastra/server handlers, all built-in server adapters (Express/Fastify/Hono/Koa), and MCP tool execution.
-
Added Fine-Grained Authorization (FGA) support for relationship-based, resource-level access control. FGA answers "can this user perform this action on this specific resource?" — enabling multi-tenant isolation and per-resource permissions. (#15410)
New interfaces: IFGAProvider (read-only checks) and IFGAManager (read + write operations) with types for access checks, resources, and role assignments.
Enforcement at all execution points: FGA checks are automatically enforced before agent execution (generate(), stream()), tool execution, workflow execution, and memory thread access. When no FGA provider is configured, all checks are skipped (backward compatible).
New utility: checkFGA() provides centralized FGA enforcement with FGADeniedError for denied checks. MastraMemory.checkThreadFGA() adds thread-level access control.
Request-aware authorization: Resource ID resolvers receive request context so route-level FGA checks can derive tenant- or request-scoped resource IDs.
Typed permission constants: Strongly-typed permission identifiers (e.g. 'agents:execute', 'workflows:execute', 'memory:threads:read') for use in authorization config and permissionMapping.
const mastra = new Mastra({
server: {
fga: new MastraFGAWorkos({ apiKey, clientId }),
},
});
-
Extend the schedules storage schema to support owned schedules and richer trigger audit. This is a breaking schema change to mastra_schedules and mastra_schedule_triggers; scheduled workflows are still in alpha so no compat shim is provided. (#16166)
Schedule gains optional ownerType / ownerId so a schedule row can be attributed to an owning subsystem (e.g. an agent that owns a heartbeat schedule). Workflow schedules leave both fields unset.ScheduleTrigger.status is renamed to outcome and the type is widened to ScheduleTriggerOutcome so future outcome values can be added without another rename.ScheduleTrigger gains a stable id primary key and new triggerKind, parentTriggerId, and metadata fields. triggerKind distinguishes schedule-fire rows from later queue-drain rows (used by upcoming heartbeat work); parentTriggerId links related rows; metadata carries outcome-specific context.- The libsql, pg, and mongodb adapters all add the new columns/indexes. Their
@mastra/core peer dependency is tightened to >=1.32.0-0 <2.0.0-0 so installing a new storage adapter against an older core (or vice-versa) surfaces a peer-dependency warning at install time instead of silently writing/reading the wrong field.
- Scheduler producer, server schemas/handler, and client SDK types are updated to use the new fields. The
triggers response on GET /api/schedules/:id/triggers now returns outcome instead of status.
- The bundled Studio (Mastra CLI) is updated to read
outcome so the schedule detail page keeps polling and rendering publish-failure rows correctly.
-
Added listResources() and readResource() abstract methods to MCPServerBase, enabling MCP servers to expose app resources. These resources power interactive UI rendering (MCP Apps) in Studio and other consumers. (#16004)
-
Added count_distinct aggregation and server-side TopK to the metrics storage API so dashboards built on high-cardinality fields (like threadId or resourceId) stay fast and bounded. (#16137)
New aggregation
getMetricAggregate, getMetricBreakdown, and getMetricTimeSeries accept aggregation: 'count_distinct' with a distinctColumn. Backends pick the most efficient native implementation — uniq on ClickHouse, approx_count_distinct on DuckDB.
distinctColumn is restricted to a low/medium-cardinality categorical allowlist (entityType, entityName, parentEntityType, parentEntityName, rootEntityType, rootEntityName, name, provider, model, environment, executionSource, serviceName). ID columns are not allowed — distinct counts over near-unique values converge to the row count and are rarely useful.
await store.getMetricAggregate({
name: ['mastra_llm_tokens_total'],
aggregation: 'count_distinct',
distinctColumn: 'model',
filters: { timestamp: { start, end } },
});
Server-side TopK
getMetricBreakdown accepts limit and orderDirection, so breakdowns never return the full cardinality of a column from the database. Ordering is always by the aggregated value; orderDirection flips between top-N (DESC, default) and bottom-N (ASC).
await store.getMetricBreakdown({
name: ['mastra_agent_duration_ms'],
aggregation: 'sum',
groupBy: ['threadId'],
limit: 20,
orderDirection: 'DESC',
});
-
Added RegexFilterProcessor — a zero-cost regex-based content filter for blocking, redacting, or warning on pattern matches in agent messages. Includes built-in presets for PII, secrets, URLs, and prompt injection patterns. Supports input, output, and streaming phases. (#16058)
-
Added scheduled workflows. Declare a schedule on createWorkflow and Mastra fires the workflow on cron with no extra wiring. (#15830)
import { createWorkflow } from '@mastra/core/workflows';
const dailyReport = createWorkflow({
id: 'daily-report',
inputSchema: z.object({ date: z.string() }),
outputSchema: z.object({ summary: z.string() }),
schedule: {
cron: '0 9 * * *',
timezone: 'America/Los_Angeles',
inputData: { date: 'today' },
},
})
.then(/* steps */)
.commit();
A workflow with a schedule is auto-promoted to the evented engine, so scheduled fires share the same execution path as manual start() calls. inputData, initialState, and requestContext on the schedule are type-checked against the workflow's schemas at definition time. Pass an array of schedules with stable ids to fire one workflow on multiple crons.
Mastra auto-instantiates a WorkflowScheduler when any registered workflow declares a schedule. The scheduler claims due schedules via compare-and-swap, so multiple instances polling the same storage cannot double-fire. Projects with no scheduled workflows pay zero cost. Configure with new Mastra({ scheduler: { tickIntervalMs, batchSize, enabled, onError } }).
Requires a storage adapter that implements the new schedules domain (@mastra/libsql and @mastra/pg ship adapters; InMemorySchedulesStorage is included for tests). Adds a croner dependency.
-
Added MCP Apps extension support (SEP-1865). MCPServer now accepts an appResources config to register interactive ui:// HTML resources. MCPClient preserves full tool _meta (including ui.resourceUri) when converting MCP tools to Mastra tools. Both advertise the io.modelcontextprotocol/ui extension capability. (#16004)
Example — MCPServer with app resources:
const server = new MCPServer({
name: 'my-server',
tools: { myTool },
appResources: {
dashboard: {
name: 'Dashboard',
description: 'Interactive dashboard UI',
html: '<html>...</html>',
},
},
});
-
Added CostGuardProcessor, a built-in processor for enforcing monetary cost limits across agent runs. Supports run, resource, and thread scopes with configurable time windows (default 7 days), blocking or warning when limits are reached. Also added onViolation callback to the base Processor interface for generalized violation handling across all processors. (#16057)
import { Agent } from '@mastra/core/agent';
import { CostGuardProcessor } from '@mastra/core/processors';
const costGuard = new CostGuardProcessor({
maxCost: 5.0,
scope: 'resource',
window: '24h',
strategy: 'block',
});
costGuard.onViolation = ({ processorId, message, detail }) => {
console.log(`[${processorId}] ${message}`, detail);
};
const agent = new Agent({
name: 'my-agent',
model: 'openai/gpt-5-nano',
inputProcessors: [costGuard],
});
-
Added listBranches and getBranch for querying named-entity invocations across traces, including nested ones. listTraces only returns root-rooted traces, so an entity that always runs as a child (e.g., an Observer agent inside a workflow) wasn't queryable before. (#16154)
// Before: nested-only entities returned nothing
await store.listTraces({ filters: { entityName: 'Observer' } }); // []
// After: one row per AGENT_RUN, WORKFLOW_RUN, PROCESSOR_RUN, SCORER_RUN,
// RAG_INGESTION, TOOL_CALL, or MCP_TOOL_CALL span
await store.listBranches({ filters: { entityName: 'Observer' } });
// Plus: fetch the subtree at any span, with optional depth
const branch = await store.getBranch({ traceId, spanId, depth: 1 });
Added getStructure({ traceId }) (canonical name for the lightweight trace skeleton; getTraceLight retained as a deprecated alias) and getSpans({ traceId, spanIds }) (batch-fetch spans by id, used internally by getBranch to avoid pulling whole traces).
-
Improved metric drilldown performance with skip indexes on the high-cardinality ID columns of metric_events. Dashboard queries that filter metrics by traceId, threadId, resourceId, userId, organizationId, experimentId, runId, sessionId, or requestId skip data chunks that don't contain the filtered value instead of scanning the full time range. (#16138)
Equality (=) and IN filters benefit automatically. Aggregations and GROUP BY queries without a filter on these columns are unaffected.
Migration
Existing deployments pick up the indexes on next start. The migration is metadata-only and instant — no table lock, no rewrite, no downtime. Insert overhead is negligible and index storage is well under 1% of table size. Existing data is indexed lazily as parts merge under normal retention; no operator action is required.
-
Added count_distinct aggregation and server-side TopK to the metrics storage API so dashboards built on high-cardinality fields (like threadId or resourceId) stay fast and bounded. (#16137)
New aggregation
getMetricAggregate, getMetricBreakdown, and getMetricTimeSeries accept aggregation: 'count_distinct' with a distinctColumn. Backends pick the most efficient native implementation — uniq on ClickHouse, approx_count_distinct on DuckDB.
distinctColumn is restricted to a low/medium-cardinality categorical allowlist (entityType, entityName, parentEntityType, parentEntityName, rootEntityType, rootEntityName, name, provider, model, environment, executionSource, serviceName). ID columns are not allowed — distinct counts over near-unique values converge to the row count and are rarely useful.
await store.getMetricAggregate({
name: ['mastra_llm_tokens_total'],
aggregation: 'count_distinct',
distinctColumn: 'model',
filters: { timestamp: { start, end } },
});
Server-side TopK
getMetricBreakdown accepts limit and orderDirection, so breakdowns never return the full cardinality of a column from the database. Ordering is always by the aggregated value; orderDirection flips between top-N (DESC, default) and bottom-N (ASC).
await store.getMetricBreakdown({
name: ['mastra_agent_duration_ms'],
aggregation: 'sum',
groupBy: ['threadId'],
limit: 20,
orderDirection: 'DESC',
});
-
- Added
listBranches and getSpans implementations. (#16154)
- Only spans recorded after this version is deployed are queryable via
listBranches; historical traces remain accessible through the existing listTraces / getTrace APIs.
-
Extend the schedules storage schema to support owned schedules and richer trigger audit. This is a breaking schema change to mastra_schedules and mastra_schedule_triggers; scheduled workflows are still in alpha so no compat shim is provided. (#16166)
Schedule gains optional ownerType / ownerId so a schedule row can be attributed to an owning subsystem (e.g. an agent that owns a heartbeat schedule). Workflow schedules leave both fields unset.ScheduleTrigger.status is renamed to outcome and the type is widened to ScheduleTriggerOutcome so future outcome values can be added without another rename.ScheduleTrigger gains a stable id primary key and new triggerKind, parentTriggerId, and metadata fields. triggerKind distinguishes schedule-fire rows from later queue-drain rows (used by upcoming heartbeat work); parentTriggerId links related rows; metadata carries outcome-specific context.- The libsql, pg, and mongodb adapters all add the new columns/indexes. Their
@mastra/core peer dependency is tightened to >=1.32.0-0 <2.0.0-0 so installing a new storage adapter against an older core (or vice-versa) surfaces a peer-dependency warning at install time instead of silently writing/reading the wrong field.
- Scheduler producer, server schemas/handler, and client SDK types are updated to use the new fields. The
triggers response on GET /api/schedules/:id/triggers now returns outcome instead of status.
- The bundled Studio (Mastra CLI) is updated to read
outcome so the schedule detail page keeps polling and rendering publish-failure rows correctly.
-
Added getMcpServerResources() and readMcpServerResource() methods to MastraClient for listing and reading MCP server resources from the client SDK. These methods enable frontend applications to fetch app resource HTML for interactive MCP Apps rendering. (#16004)
const client = new MastraClient();
// List resources on an MCP server
const resources = await client.getMcpServerResources('my-server');
// Read a specific app resource
const resource = await client.readMcpServerResource('my-server', 'ui://calculator/app');
-
Added schedule methods to the client for the new scheduled workflows feature. (#15830)
import { MastraClient } from '@mastra/client-js';
const client = new MastraClient({ baseUrl: 'http://localhost:4111' });
const schedules = await client.listSchedules({ workflowId: 'daily-report' });
const schedule = await client.getSchedule('wf_daily-report');
const triggers = await client.listScheduleTriggers('wf_daily-report', { limit: 50 });
await client.pauseSchedule('wf_daily-report');
await client.resumeSchedule('wf_daily-report');
Pause is durable across redeploys. Resume recomputes the next fire time from now so a long-paused schedule does not fire a backlog.
-
Added listBranches and getBranch endpoints. Use these to find specific runs of an agent, workflow, tool, or processor — even when they are nested inside another trace — and to fetch the subtree of spans rooted at any single span. (#16177)
GET /observability/branches?spanType=agent_run&entityName=Observer
GET /observability/traces/:traceId/branches/:spanId?depth=1
Each row in listBranches is a single anchor span (one of AGENT_RUN, WORKFLOW_RUN, PROCESSOR_RUN, SCORER_RUN, RAG_INGESTION, TOOL_CALL, MCP_TOOL_CALL), so entities that always run as a child (e.g., an Observer agent inside a workflow) — previously not listable through listTraces — are now queryable via the HTTP API. getBranch accepts an optional depth (0 = anchor only; omitted = full subtree).
Follow-up to https://github.com/mastra-ai/mastra/pull/16154 which added the underlying @mastra/core storage APIs.
-
Fixed Vector resource return types so they match what the server actually returns. Previously the types declared shapes that did not exist at runtime, leading to runtime failures with no TypeScript errors. (#16036)
What changed
vector.getIndexes() now returns string[] (was { indexes: string[] })vector.upsert() now returns { ids: string[] } (was string[])vector.query() now returns QueryResult[] (was { results: QueryResult[] })
Before
const response = await client.getVector('docs').getIndexes();
console.log(response.indexes); // undefined at runtime
After
const indexes = await client.getVector('docs').getIndexes();
console.log(indexes[0]); // 'docs-index'
Closes #15089.
-
- Added
listBranches and getSpans implementations. (#16154)
- Historical span data is queryable immediately; no migration required.
-
Added count_distinct aggregation and server-side TopK to the metrics storage API so dashboards built on high-cardinality fields (like threadId or resourceId) stay fast and bounded. (#16137)
New aggregation
getMetricAggregate, getMetricBreakdown, and getMetricTimeSeries accept aggregation: 'count_distinct' with a distinctColumn. Backends pick the most efficient native implementation — uniq on ClickHouse, approx_count_distinct on DuckDB.
distinctColumn is restricted to a low/medium-cardinality categorical allowlist (entityType, entityName, parentEntityType, parentEntityName, rootEntityType, rootEntityName, name, provider, model, environment, executionSource, serviceName). ID columns are not allowed — distinct counts over near-unique values converge to the row count and are rarely useful.
await store.getMetricAggregate({
name: ['mastra_llm_tokens_total'],
aggregation: 'count_distinct',
distinctColumn: 'model',
filters: { timestamp: { start, end } },
});
Server-side TopK
getMetricBreakdown accepts limit and orderDirection, so breakdowns never return the full cardinality of a column from the database. Ordering is always by the aggregated value; orderDirection flips between top-N (DESC, default) and bottom-N (ASC).
await store.getMetricBreakdown({
name: ['mastra_agent_duration_ms'],
aggregation: 'sum',
groupBy: ['threadId'],
limit: 20,
orderDirection: 'DESC',
});
-
Added support for icon-and-description layout in Notice by making title optional. When omitted, the notice renders as a single row with icon and description, useful for inline contextual messages. (#16033)
// Before — title required
<Notice variant="info" title="Heads up">Some message.</Notice>
// After — title optional, single-row layout
<Notice variant="info">Some message.</Notice>
-
Improved trace timeline span controls. Added tooltips with row counts to the expand-children, expand-all-descendants, and expand-at-this-level buttons. The expand-children button now collapses only the direct children rather than the entire subtree, and the descendants column gained a matching collapse-all-descendants action. Root spans show a single Expand all / Collapse all button using outward/inward double-chevrons. (#16173)
-
Refreshed toast styling so it aligns with the Notice component and lets sonner own the layout. (#16144)
What changed for users:
- Variant toasts (success / error / warning / info) now render with the same notice color tokens as the
<Notice> component, including bg, border and text color in both light and dark mode.
- Sonner's native layout is back in charge — the loader on
toast.promise, the close button position, the icon placement and the mobile width all work as documented instead of fighting custom overrides.
- The native close button has its own polished hover: it blends with the toast at rest and lifts with a tinted bg + stronger border on hover, in every variant and theme.
- Sticky toasts can be made truly non-dismissible by passing both
dismissible: false and closeButton: false.
toast.success / error / warning / info now return sonner's toast id (or an array of ids when called with an array of messages) so callers can keep dismissing or updating the toast they created.
-
Added a Scorer span type style on the trace timeline and a colored type dot before each span name so spans are visually flagged in both the name and timing columns. (#16160)
-
Migrated Files/Skills tabs and agent page tabs (Chat/Editor/Evaluate/Review/Traces) to the design-system Tabs component for consistent styling and accessibility (Radix tablist, arrow-key navigation). Also added a cursor-pointer on the Tab trigger and a disabled prop on the DS Tab. (#16148)
-
Added MCP Apps extension support (SEP-1865). MCPServer now accepts an appResources config to register interactive ui:// HTML resources. MCPClient preserves full tool _meta (including ui.resourceUri) when converting MCP tools to Mastra tools. Both advertise the io.modelcontextprotocol/ui extension capability. (#16004)
Example — MCPServer with app resources:
const server = new MCPServer({
name: 'my-server',
tools: { myTool },
appResources: {
dashboard: {
name: 'Dashboard',
description: 'Interactive dashboard UI',
html: '<html>...</html>',
},
},
});
-
Added an informational notice on the trace data panel pointing users to Mastra Studio (local or deployed) when "Evaluate Trace" and "Save as Dataset Item" actions are not available in the current view. (#16157)
-
Fixed pointer cursor on interactive form controls (Button, SelectTrigger, SelectItem) for better affordance. (#16140)
