Repository navigation
Highlights
Storage Version 2 for Agents & Evented Workflows (much smaller writes + faster runs)
Agents (createDurableAgent, createEventedAgent) and evented workflows can now opt into experimental storageVersion: 2, storing runs as a header + per-step rows so long runs write only deltas. This dramatically cuts payload sizes and storage churn (example: 98 MB → 11 MB published; 75 MB → 3.1 MB written) and standardizes APIs like result.steps() async + getState().
Automatic Workflow Crash Recovery Loop + Smarter Broker-Aware Recovery
Mastra now includes a workflow recovery loop started by startWorkers() that restarts crashed default-engine runs without waiting for another instance boot, using a leader election lease across instances. Recovery behavior is also now broker-aware (via pubsub.redeliversUnacked): on Redis/Valkey Streams and Google Cloud Pub/Sub, instances stop “restarting everything on boot” and instead let the broker redeliver unacked step messages to prevent duplicate concurrent execution.
Knowledge Lifecycle APIs: Move Pages & Re-embed Existing Content
Knowledge gets two major operational APIs: knowledge.movePage() to move a page (and descendants) without losing IDs/embeddings/links, and knowledge.reembed() to (re)embed existing pages/notes in resumable batches—critical for backfilling content or switching embedders without rewriting pages.
New Hosted Platform Clients: @mastra/platform (Platform Memory/Knowledge + Browser Sessions)
Introduced @mastra/platform, adding hosted Platform Memory and Knowledge clients (PlatformMemory, PlatformKnowledge) plus Platform Workspace re-exports and a new PlatformBrowser (Stagehand browser backed by Platform browser sessions). This enables running agents against managed Memory/Knowledge and provisioning remote browser sessions via Platform APIs with env-based credentials.
MCP Apps for Observability in Chat Clients (Studio views embedded in MCP results)
Mastra’s built-in MCP server can now render observability results as interactive Studio-based MCP Apps (Trace Viewer + Observability Explorer) in clients that support MCP Apps (e.g., Claude), reducing model context by ~5–8x by sending compact text to the model and full rows as structured app content. New controls include server.mcp.apps, server.mcp.studioUrl, plus MCP SDK support like appsRequireClientSupport and configurable maxRequestBodySize.
Breaking Changes
- Knowledge alpha scope matching changed:
$paramnow matches exactly one segment; raw:is no longer allowed inside a scope segment, requiring canonical encoding viaencodeKnowledgeScopeId/decodeKnowledgeScopeId(existing data is not rewritten, so some scopes may become “new/empty” unless you update IDs). - @mastra/factory:
newestOpenPullRequestNumberis no longer exported from@mastra/factory/boards; useworkingPullRequest(item)+pullRequestSourceNumber. - @mastra/playground-ui:
ListSearchandSearchFieldBlockare removed; migrate toSearchInput. Also removedSectionCardandCardHeadingin favor of settings components. - @mastra/factory:
MastraFactoryno longer acceptsintake: { evaluator }(set via env/project config instead); passing it now throws at startup.
Changelog
@mastra/core@1.84.0
Minor Changes
-
Added
collectionExists(name)to Factory storage so a domain can tell whether a table already exists before registering it. Supported byLibSQLFactoryStorageandPgFactoryStorage; it is an optional capability, so other backends keep working unchanged. (#30488)if (!storage.collectionExists || (await storage.collectionExists('work_items'))) { await storage.ensureCollections([WORK_ITEMS_SCHEMA]); }
Also in: @mastra/libsql@1.31.0, @mastra/pg@1.37.0
-
Added a workflow recovery loop. A default-engine workflow run whose instance crashed is now restarted without waiting for another instance to boot (#28712). (#30281)
startWorkers()starts the loop on an instance that runs the orchestration worker. Everyrecovery.workflowScanIntervalMs(60 seconds by default, give or take a fifth), it restarts the default-engine runs that stopped, by the same rule asrestartAllActiveWorkflowRuns(). A crashed instance's run is restarted at the first pass after its lease (MASTRA_AGENT_THREAD_LEASE_TTL_MS, 15 seconds by default) expired andrecovery.workflowGraceMspassed, so within about one scan interval of that.Instances that share a storage adapter elect one loop leader through a lease row in storage, and only the leader's loop lists runs. The leader keeps the role until its
stopWorkers()orshutdown()hands it back, or its lease expires after a crash. The leader applies to the loop only:restartAllActiveWorkflowRuns()at boot still restarts each instance's own stopped default-engine runs. The loop recovers only the workflows the leader registers, and a run it restarts executes on the leader.const mastra = new Mastra({ recovery: { workflowScanIntervalMs: 30_000 }, });
The loop never restarts evented runs, and doesn't run when
recovery.workflowsis'off'or on a storage adapter without run-ownership support.restartAllActiveWorkflowRuns()no longer schedules a check of its own for runs it found live or in their grace period; the loop looks at them again. -
Add shared contracts for experimental Platform trace page. (#30512)
-
Evented workflows from
@mastra/core/workflows/eventednow accept the experimentalstorageVersion: 2option. Before, setting it on an evented workflow threw. On version 2, each step's message carries only the previous step's result and the state changes, and the engine loads the rest from storage. In anEventedAgentrun with 16 tool calls on@mastra/pg, published messages fell from 98 MB to 11 MB, storage writes from 75 MB to 3.1 MB, and run time from 3.9 s to 2.7 s. (#29370)const workflow = createEventedWorkflow({ id: 'my-workflow', inputSchema, outputSchema, options: { storageVersion: 2 }, });
As on the default engine,
stepson a version 2 run's result is an async function, whichonFinishandonErrorreceive too:const result = await run.start({ inputData }); const steps = await result.steps();
On both storage versions, a nested run's messages no longer carry a copy of the parent run's step graph. On version 1, this cut the messages an agent run with 16 tool calls publishes by more than a quarter.
-
restartAllActiveWorkflowRuns()no longer restarts evented workflow runs that a broker recovers on its own, and restarts a default-engine run only once it stopped (#28712). (#30279)Evented runs on a broker. With a pubsub whose broker redelivers a dead worker's unacked messages (Redis Streams, Valkey Streams, Google Cloud Pub/Sub), booting instances no longer restart evented runs. Before, every instance that booted restarted every active evented run, so steps ran again on several instances at once. Now the broker hands the stopped step's message to another worker, and the run goes on from there. Pubsub implementations report this through the new
redeliversUnackedgetter, which defaults tofalse.With Redis or Valkey Streams, keep
reclaimIdleMsat 30 seconds or more (the default is 60 seconds). A message reclaimed sooner can arrive while the dead worker's step fence is still held, and is then dropped as a duplicate.Booting instances still restart these evented runs, each of them, as before:
- scheduled runs, whose events stay in the process that fired them
- runs on the default in-process
EventEmitterPubSubor on the Unix socket pubsub. Several instances that share one storage aren't supported for evented workflows with these; use a broker.
Known limits on a broker. These evented runs stay
runninguntil you callrestart()on them. Before, the next booting instance restarted them.- A sleeping run whose instance exits, after a crash or during a normal deploy. The sleep's timer lives in that process.
- A run whose step message Redis or Valkey Streams trimmed. The streams trim to
maxStreamLengthentries (10,000 by default), pending ones included, so a step that is still running while that many newer events are published loses its message if its instance then exits. RaisemaxStreamLengthif you run long steps with a high event volume. - A run whose message the broker dropped after
maxDeliveryAttemptsorinFlightTimeoutMs, a run whose failure couldn't be published after several attempts, and runs on a Redis instance that restarted without persistence.
Default-engine runs. A
runningorwaitingrun counts as stopped when no instance holds its run lease and neither the run nor that lease changed forrecovery.workflowGraceMs(2 seconds by default). A run that stopped more recently is left to the workflow recovery loop thatstartWorkers()starts. Without run fencing in the store, every active run is still restarted, as before.const mastra = new Mastra({ recovery: { workflowGraceMs: 5_000 }, });
Recovery is also faster when many runs are active: it lists runs without their step results and reads a run's snapshot only when it restarts it. With 3,000 active runs that another instance holds, among 30,000 finished runs, a call takes about 30 ms instead of 1.8 s on Postgres and 45 ms instead of 630 ms on LibSQL. A call made while another is still handing out restarts joins that call, and
shutdown()waits, withindrainTimeout, for a recovery call in progress and the runs it is restarting.A default-engine nested run resumed directly now keeps its parent from being restarted while it runs. On stores without atomic status updates, it keeps itself from being restarted instead.
-
Added
knowledge.movePage()to move a page, with its child pages, to a new parent or scope from your app. The page keeps its ID, notes, pins and embeddings, and links by path follow it, so a sync that sees a page move at its source no longer has to remove and re-create it. (#30631)await knowledge.movePage({ scope: 'docs:acme', path: 'inbox/plan', parent: 'projects/q4' });
Links by name now stay correct when a page moves or a new page takes a name. A page moved to another scope, and every page under it, re-resolves its
[[Name]]links in the new scope. A link that pointed at one page by name stops resolving once a second page answers to that name. When more than 99 pages share that name, the write logs a warning andknowledge.reindexLinks()repairs the rest. -
Added
knowledge.reembed()to embed Knowledge pages and notes that already exist, such as content written beforevectorandembedderwere configured or after switching embedders. It runs in batches with a resumable cursor, doesn't change the pages, lists failures and pages over the chunk cap, and stops early with a cursor when the embedder keeps rate limiting. (#30603)let cursor: string | undefined; do { const result = await knowledge.reembed({ scope: 'org:acme', cursor }); if (result.rateLimited) await new Promise(resolve => setTimeout(resolve, 60_000)); cursor = result.nextCursor; } while (cursor);
-
Breaking (Knowledge alpha): a
$paramin a Knowledge scope pattern now matches exactly one segment, so scope values can no longer contain a raw:. Before, the last param took the rest of the address, soorg:acme:viewercounted as anorg:$orgIdscope and its holder got that pattern'sselfrights there. (#30019)- Agent
scopesare canonical addresses. An id containing:,/,#or%must be encoded with the newencodeKnowledgeScopeId. The raw form (e.g.org:a:bagainstorg:$orgId) fails with "does not match a declared scope type", and%is always read as an escape, so each scope has one spelling. - Memory ids are bound encoded: resource
slack:U123becomesresource:slack%3AU123. - Patterns of one type with different segment counts no longer overlap, so
org:$orgIdandorg:$orgId:viewercan be declared side by side. decodeKnowledgeScopeIdreads an id back from one segment of an address.
import { encodeKnowledgeScopeId } from '@mastra/core/knowledge'; const scope = `org:${encodeKnowledgeScopeId('auth0|a:b')}`; // 'org:auth0|a%3Ab', pass this in Agent scopes
No data is rewritten:
- Ids with a colon in the last segment get new addresses. Before, the last segment kept a raw
:(resource:slack:U123); now it is encoded (resource:slack%3AU123), so a run reaches a new, empty scope, and pages, pins and notes stored under the old address stay there unreached. Nothing moves them. - Every other id keeps its address if you pass it through
encodeKnowledgeScopeId./,#and%were already encoded the same way, soorg:${encodeKnowledgeScopeId('a/b')}reaches rows stored from the raworg:a/b. Passing the old raw string unchanged does not:org:a/bis refused, and a raw scope that happened to contain an escape (org:a%3Ab, once stored asorg:a%253Ab) now means the ida:b. - Stale rows get nothing from their new match. A stored scope row whose address now matches a different declaration than the one it was created under (e.g.
org:acme:viewercreated underorg:$orgId, onceorg:$orgId:vieweris declared) gets none of the new declaration's access. It is never abelongsToparent, and using it as a scope of the new declaration fails with an error. Prefix grants of the declaration it was created under still let their holders read it, as before, without a role on it.
- Agent
-
Knowledge storage can supply scope declarations, access rules included. (#29428)
A store returns declarations from
getScopeDeclarations()(none by default). Knowledge merges them under its config's: the config wins on a key both declare, and a declaration that doesn't compile is skipped with a warning. When stored scopes come from a skipped declaration, the declaration check's error names that declaration and why it was skipped, so it can be fixed in the store. The store's answer is reused for 30 seconds and read again afterrenameScopeDeclaration, so a declaration the store adds, removes or changes (access rules included) applies within that window without a store read on every call. Revoking access through the store can therefore take up to 30 seconds to take effect.class ImportingKnowledgeStorage extends InMemoryKnowledgeStorage { override async getScopeDeclarations() { return { 'imports:$name': {}, 'linear:$account:$connection': { access: [{ principal: 'imports:all', role: 'viewer' }] }, }; } }
Runs that hold
imports:allthen read every Linear connection's pages. -
Added the
appsandstudioUrloptions toServerMCPConfig(server.mcp), for the built-in MCP server's MCP Apps.apps: falseturns them off, andstudioUrlsets where their Open in Studio button points. (#30244)export const mastra = new Mastra({ server: { mcp: { apps: true, studioUrl: 'https://studio.example.com', }, }, });
-
Added
agent.recoverResume()to finish a tool approval or resume after the process handling it crashed, without asking for the decision again. Previously the approval or resume data only lived in the memory of that process, so a crash between approving and the tool running lost the answer and left the run stuck. The decision and the targeted tool call are now saved with the resume claim, andrecoverResume()replays them once the claim is abandoned. Fixes #30285. (#30330)// The process that called approveToolCall({ runId, toolCallId }) crashed. const stream = await agent.recoverResume({ runId });
-
Added
updateStateto workflow steps, workflow tools,.map()functions, loop and branch conditions, and sleep functions. It merges the top-level keys it's given into the workflow state, validates the merged state against the step'sstateSchema, and leaves keys it wasn't given alone, including changes parallel steps made. A key set toundefinedis removed. (#29370)setStatekeeps its existing contract: pass the full state, the value is validated on its own, and a second call in the same step replaces the first.// Before: copy the whole state so the other keys survive await setState({ ...state, count: state.count + 1 }); // After: pass only the keys that change await updateState({ count: state.count + 1 });
-
Replaced experimental textSearch contracts and capabilities with token predicates for supporting hosts. (#30511)
-
Added run metadata to background process callbacks. (#30161)
backgroundProcessescallbacks onexecute_commandnow receive, when available, theagentId,threadId,resourceId, andrunIdof the call that started the process, so hosts can route exit notices to the right conversation.onExitalso receiveskilledByAbort, which istruewhen the abort signal fired (the run's signal by default) and killed the process.backgroundProcesses: { onExit: ({ pid, exitCode, threadId, killedByAbort }) => { if (!killedByAbort) notifyThread(threadId, `Process ${pid} exited with code ${exitCode}`); }, },
truncateOutputandDEFAULT_TAIL_LINESare now exported from@mastra/core/workspace, so hosts can trim process output the same wayexecute_commanddoes. -
Added
getRunOwnerships({ runIds })to workflows storage (#28712). It returns the ownership records of many runs at once, in aMapkeyed by run ID; runs without a stored record are left out. Stores without a batch query fall back to reading each run withgetRunOwnership(), at most 8 at a time. (#30274)const workflows = await mastra.getStorage()?.getStore('workflows'); const owners = await workflows?.getRunOwnerships({ runIds: ['run-1', 'run-2'] }); owners?.get('run-1')?.live; // true while the run's lease hasn't expired
The in-memory store now honors
summary: trueinlistWorkflowRuns(): each run's snapshot comes back as onlystatus,timestampand, for nested runs,parentWorkflow: { workflowId, runId }.const { runs } = await workflows!.listWorkflowRuns({ workflowName: 'charge', status: 'running', summary: true }); runs[0]?.snapshot; // { status: 'running', timestamp: 1731456000000, parentWorkflow: { workflowId: 'order', runId: 'run-1' } }
In the in-memory store,
updateWorkflowResults(),updateWorkflowState()andupdateWorkflowRunHeader()now move a run'supdatedAt, as they do in the database adapters. -
Added
getState()to workflow steps, tools that run inside workflows,.map()functions, loop and branch conditions, and sleep functions. It resolves to the current workflow state, including the step's ownsetStatechanges. Pass top-level keys to get only those keys. (#29370)Reading
statein a run stored with the experimentalstorageVersion: 2option now throws, on both the default and evented engines. UsegetState()instead:// Before execute: async ({ state }) => state.count; // After execute: async ({ getState }) => (await getState(['count'])).count;
-
Added
ModelRouterLanguageModel.isGatewayMemoryManaged(). It reports whether the Mastra Gateway serves Observational Memory for the credential the model will use, so framework code can keep memory local when the gateway can't serve it. A gateway project key is served by the gateway. An organization key (msk-gateway-…,mskv2_…) is served by a gateway without the memory API. A credential that can't be resolved — including one the gateway reports as missing — is thrown instead of reported as local, so a caller never mistakes a failed lookup for local ownership and the gateway and the local store can't both save the same conversation (#30391). (#30414)const model = new ModelRouterLanguageModel('mastra/openai/gpt-6.1-sol'); if (await model.isGatewayMemoryManaged()) { // The gateway stores the thread's observations. } else { // Memory has to stay local. }
-
Added an experimental
storageVersionoption tocreateDurableAgentandcreateEventedAgent. Set it to2to store new runs as a run header plus one row per step, so each save writes only what changed instead of rewriting the whole run. This keeps storage writes small for long agent runs. (#29370)const durableAgent = createDurableAgent({ agent, storageVersion: 2 });
Storage version 2 works with in-memory storage,
@mastra/pg, and@mastra/libsql. On other adapters, the agent logs a warning and stores new runs as version 1. The default stays1, and runs stored before you change the option keep their version.
Patch Changes
-
Fixed retries in
dountilanddowhileloops on the evented engine. (#30383) -
Fixed durable and evented agent streams so completion and cleanup from an earlier execution preserve a newer or resumed run's status, live state, and replay history. (#30376)
-
Fixed restart and time travel of workflow runs that contain a
.sleep()or.sleepUntil()without anid. (#30397) -
Exclude uncheckpointed durable agent output when replaying a run after an ownership takeover, while retaining previously checkpointed steps. (#28530)
-
Fixed
DurableAgent.recover()silently continuing a recovered run without its processors or memory. (#29153) -
Retries in
fetchWithRetrynow wait through the shared retry delay helper. (#29100) -
Background task lease tests can now run with a lease shorter than 3 seconds through an internal test-only setting, so lease-expiry tests finish in milliseconds instead of seconds. (#29100)
-
Updated the bundled AI SDK provider utilities to the latest patch releases of each supported version (
@ai-sdk/provider-utils4.0.66 and 5.0.81,@ai-sdk/provider4.0.38). (#30518) -
Fixed Gateway v2 deployments showing models they cannot use. (#29445)
-
Fixed resumed step retries and
perStepruns on the evented engine. (#30398) -
Fixed agents that resolve their model, instructions, or memory from request context failing to run when a signal wakes a thread whose claimed owner runs on another server. (#29447)
-
Fixed processor workflows that use
ProcessorStepOutputSchemadroppingproviderMetadatain theoutputStepphase. (#30331) -
Fixed web search on models served through the Mastra gateway. (#30239)
-
Fixed slow handling of Gateway base URLs and Supabase URLs that contain very long runs of
/. (#30577)Also in: @mastra/auth-supabase@1.2.1
-
Channel agents now always reply when someone tags them in a public channel or thread. (#30277)
Also in: @mastra/factory@0.29.0
-
Removed the 10 ms pause after every memory save. (#29148)
-
Fixed evented workflows ending a run twice when two
foreachiterations failed at the same time. (#29370)Also in: @mastra/convex@1.9.1
-
Fixed durable agents sending the model a background tool's placeholder instead of its result. (#29370)
-
A notification sent with
ifIdle: { behavior: 'persist' }now stays persist-only when its delivery is deferred. (#30623) -
Fixed a run waiting on a tool approval losing its saved state when the thread lease expired. (#27734)
-
Fixed durable agents ignoring an agent-level pubsub for run streams. (#30229)
-
Fixed a
.foreach()run staying stuck as running when the first failed item's failure could not be sent. (#29370)Also in: @mastra/client-js@1.61.0, @mastra/convex@1.9.1, @mastra/libsql@1.31.0, @mastra/pg@1.37.0, @mastra/redis-streams@0.9.0, @mastra/server@1.84.0
-
Fixed
run.restart()running a step again when the workflow run finished or suspended afterrestart()read it but beforerestart()took it over from the process running it. (#30399) -
Core's own unit tests can now shorten internal drain budgets, snapshot polls and the post-save pause in message history. (#29134)
-
Fixed
DurableAgent.recover(),recoverActiveRuns()and automatic recovery skipping the agent'sdefaultOptionsonFinish,onErrorandonAbortcallbacks. (#30278) -
Coding agents now subscribe their thread to an existing pull request or merge request when they start working on it, such as reviewing it, fixing merge conflicts, addressing review comments, fixing CI, or pushing to its branch. (#30675)
Also in: @mastra/factory@0.29.0
-
Corrected the
Mastra.addTool()JSDoc. (#30681) -
execute_commandnow resolves relative paths against the workspace directory, not the sandbox's own default working directory. (#30210)Also in: @mastra/code-sdk@1.19.1
-
Fixed evented workflows running a step again when its event arrives after the step finished, for example a broker redelivery or a message that waited in a queue while
restart()ran the step (#28712). (#30275) -
Fixed workflow
.sleep()and.sleepUntil()waits longer than about 24.8 days ending almost immediately. (#30395) -
Fixed time travel hanging on evented workflows whose
shouldPersistSnapshotskips running snapshots, when replaying from a step that comes before a failedforeachstep. (#29370) -
Fixed AgentController sessions pausing every tool call for approval and running a step's tool calls one at a time. (#30151)
-
Fixed a
.foreach()over a nested workflow on a run stored with the experimentalstorageVersion: 2option only keeping the last item's run. (#29370)Also in: @mastra/client-js@1.61.0, @mastra/convex@1.9.1, @mastra/libsql@1.31.0, @mastra/pg@1.37.0, @mastra/redis-streams@0.9.0, @mastra/server@1.84.0
-
Fixed durable agent runs failing with
DURABLE_AGENT_EXECUTION_UNVERIFIEDwhen an ownership check took longer than the lease TTL (15 seconds by default) while the same process still held the run. (#30386) -
Fixed workflow recovery restarting a run that is still executing, which ran its steps twice. (#30384)
-
Fixed evented workflows storing the wrong workflow state after parallel branches changed a state that has a top-level
outputarray. (#29370) -
processToolResultnow sees and can rewrite a tool'stoModelOutputresult. (#30401) -
Fixed background tasks with
timeoutMs: 0being stopped right away as timed out. (#30381) -
Improved workflow recovery so it lists active runs for at most five workflows at a time instead of all at once. (#30396)
-
Fixed extra model step and model inference spans in traces when
onStepFinishtakes time to finish. (#30442)
@mastra/arize@1.4.0
Minor Changes
-
Updated to the OpenTelemetry semantic conventions 1.41.0 attributes from
@mastra/otel-exporter. Fixed the finish reason on model calls. It showedstopfor every call, and now shows the real reason, such astool-callsorlength. Stop sequences now also appear in the invocation parameters. (#30342)Also in: @mastra/arthur@0.5.0
Patch Changes
-
Raised the minimum versions of the OpenTelemetry SDK and OTLP exporter dependencies (
@opentelemetry/sdk-trace-baseand@opentelemetry/core^2.12.1, OTLP exporters^0.223.1) so they no longer resolve to releases that pin@opentelemetry/resources2.12.0, which is affected by security advisory GHSA-qrww-3xmv-qhgm. (#30580)Also in: @mastra/arthur@0.5.0, @mastra/laminar@1.3.33, @mastra/otel-exporter@1.6.0
@mastra/clickhouse@1.30.1
Patch Changes
-
Reject unsupported token search predicates. (#30511)
Also in: @mastra/duckdb@1.19.1, @mastra/pg@1.37.0
-
Fixed
listScoresin the ClickHouse store returning scores in an unstable order when several scores share the same timestamp or value. (#29102)
@mastra/client-js@1.61.0
Minor Changes
-
Add getTracePage() for Platform. (#30512)
-
Updated experimental search types for supporting hosts. (#30511)
Patch Changes
-
Removed
save_messagesandsearch_memoryfrom the built-in MCP memory toolset, and added a read-onlyget_working_memorytool. (#30245)Also in: @mastra/server@1.84.0
-
Reject client-tool telemetry with reversed timestamps without interrupting tool execution. (#30293)
-
Stop the JavaScript client from repeating state-changing requests by default. (#30434)
@mastra/cloudflare@1.8.1
Patch Changes
-
Listing workflow runs with
summary: truenow returns only each run'sstatus,timestampand, for nested runs,parentWorkflow: { workflowId, runId }(#28712). (#30274)Also in: @mastra/cloudflare-d1@1.5.1, @mastra/dsql@1.5.8, @mastra/mongodb@1.27.1, @mastra/mssql@1.11.2, @mastra/mysql@0.17.1, @mastra/oracledb@0.5.7, @mastra/spanner@1.12.1
@mastra/code-sdk@1.19.1
Patch Changes
-
Fixed
mastracodecrashing on startup after a fresh install. (#30425) -
Fixed custom OpenAI-compatible providers so they only ever authenticate with the API key saved on the provider itself. (#29879)
-
@mastra/code-sdknow ships its own copy of the Knowledge scope id encoder instead of importingencodeKnowledgeScopeIdfrom@mastra/core. (#30427) -
Fixed provider safety rejections losing their cause. (#30294)
-
Fixed scheduled and notification runs pausing every tool call for approval when YOLO is off. (#30151)
-
Fixed
ask_userquestions not firing permission hooks. (#30301) -
Mastra Code's Knowledge scopes now use canonical addresses, matching
@mastra/core's one-segment scope values. (#30019)Also in: @mastra/factory@0.29.0
-
Fixed plan feedback stopping the run. (#30524)
-
Held plugin errors until someone listens.
PluginManager.onPluginErrornow receives errors reported before it subscribed, such as a plugin signal provider failing to start while Mastra Code boots. (#30428) -
Kept a plugin running when its reload fails. A reload that fails for a plugin that was working (a bad update, a throwing resolver) now keeps the plugin's last good tools, signal providers and version stamp, and records the error as
reloadErrorinstead of removing the plugin. (#30412) -
Stop registering the built-in outcome and efficiency scorers on every Mastra Code session. (#30363)
@mastra/connect@1.4.1
Patch Changes
-
Changed the default model of the OpenAI create-image tool from
gpt-image-1togpt-image-2.5-sunburst. (#30364) -
The
resourceIdcallback onuserConnectRoutes()now receives the authenticated user as a typedMastraUser, the sameuserthat agent callbacks such astoolsreceive. (#30340) -
Fixed
posthog_run_queryfailing provider-response validation whenever PostHog returned column types, which it does for every query with columns, evenselect 1. (#30541)
@mastra/convex@1.9.1
Patch Changes
-
Fixed Convex vector queries applying only the first operator in a field condition. (#30469)
-
Listing workflow runs with
summary: truenow returns only each run'sstatus,timestampand, for nested runs,parentWorkflow: { workflowId, runId }, so callers that only need run metadata no longer receive full snapshots (#28712). (#30274)Also in: @mastra/dynamodb@1.5.2, @mastra/redis@1.4.14, @mastra/upstash@1.6.2, @mastra/valkey@0.2.10
@mastra/couchbase@1.1.5
Patch Changes
- Couchbase vector queries now log a warning the first time a metadata filter is passed. (#30446)
@mastra/daytona@0.11.6
Patch Changes
- Switched from
@daytonaio/sdkto@daytona/sdk, the new name Daytona publishes its SDK under. (#28995)
@mastra/dynamodb@1.5.2
Patch Changes
-
Added a batch read of workflow run ownership (#28712). (#30274)
Also in: @mastra/libsql@1.31.0, @mastra/mongodb@1.27.1, @mastra/mssql@1.11.2, @mastra/mysql@0.17.1, @mastra/pg@1.37.0, @mastra/redis@1.4.14, @mastra/upstash@1.6.2, @mastra/valkey@0.2.10
@mastra/e2b@0.18.0
Minor Changes
-
E2B sandboxes can run agent commands as a second, unprivileged OS user, and S3 and GCS mounts can name the user that owns their files. (#30433)
E2BSandboxtakes auseroption. Every command the agent runs —executeCommandand background processes alike — runs as that user instead of the template's default user, which has to keepsudobecause mounting needs it. Without the option, nothing changes.S3FilesystemandGCSFilesystemtake anowneroption,{ uid, gid }. It sets the ownership of the files inside the mount, so a command user other than the one that mounts can read and write them. Without it, the mount keeps probing the default user's uid and gid.Together, the two options let agent commands run as a user that cannot read the credentials staged for a mount or become root:
const workspace = new Workspace({ mounts: { '/s3-data': new S3Filesystem({ bucket: 'my-bucket', region: 'us-east-1', owner: { uid: 1001, gid: 1001 }, }), }, sandbox: new E2BSandbox({ user: 'agent' }), });
These options change command identity and mount ownership, not every operation: file tools and other files-API calls still run as the template's default user, which keeps the privileges mounting needs.
The
usermust already exist in the sandbox template.Also in: @mastra/gcs@0.4.0, @mastra/s3@0.7.0
@mastra/factory@0.29.0
Minor Changes
-
New factories no longer create database columns and tables that nothing reads. Existing factories keep working: the old columns and their data stay in place, and the factory simply stops writing them. (#30495)
Removed
- The
filesystem_snapshotsandintake_label_routestables are no longer created, and the background file-listing capture that filledfilesystem_snapshotsno longer runs. - The
waitForPendingFilesystemCaptureexport is removed. Remove any call to it; there is nothing left to wait for. - Project repository responses no longer include
sandboxWorkdirorlastBuiltAt, and linking a repository no longer acceptssandboxWorkdir.
Upgrading
Update
@mastra/pgor@mastra/libsqltogether with@mastra/factory. Older adapter versions keep the retired columns required on existing databases, which makes card, rule and repository writes fail. - The
-
Organization admins can now create skills for one Factory from Settings › Skills, without redeploying. Choose New skill, give it a name, description and instructions, and the Factory's sessions can load it from their next start. A phase of the Factory's boards can also run it as
runner.skill. Created skills show a Custom badge and can be edited or deleted from the same page. Creating and deleting are recorded in the audit log asfactory.skill.createdandfactory.skill.deleted. (#30647)A board phase runs a created skill by its name, like any other skill:
await factory.upsertBoard( { key: 'notes', name: 'Release notes', phases: [ { key: 'queued', name: 'Queued', kind: 'resting', nextPhases: ['writing'] }, { key: 'writing', name: 'Writing', kind: 'working', runner: { context: 'writer', skill: 'release-notes' }, nextPhases: ['done'], }, { key: 'done', name: 'Done', kind: 'terminal' }, ], }, // Each project listed must have created `release-notes`; a board for 'all' projects may only run the app's skills. { projects: [{ orgId, factoryProjectId }] }, );
If the app later ships a skill under the same name, the app's skill takes over the name and the Factory's text becomes an edit of it, which Revert to original removes.
-
Pull requests link to their issue's card on their own. A pull request that closes an issue now links to that issue's unfinished card, whoever opened it and whichever board the card is on. Linking moves nothing by itself: the card gets a
pull_request.openedevent, and the default ruleTrusted pull requests take a waiting issue to Reviewmoves a waiting card to Review when the pull request's author is trusted. Stored routes that joined pull requests to cards (joinClosedIssue: true) are switched off and kept for history. A join route an admin had changed gets arule_retiredentry in the intake decision log naming it, since the default rule may not cover what it did. New join routes are refused with422 join_retired. (#30491)Nothing runs on an outside author's pull request until a person picks it. An outsider's linked pull request never becomes the card's working pull request on its own, its pushes and review requests don't re-review it or move the card, and its comments don't reach the card's sessions. Its merge or close still moves the card. A person picks it with the new endpoint:
curl -X PUT "$FACTORY_URL/web/factory/projects/$PROJECT/work-items/$CARD/working-pull-request" \ -H 'content-type: application/json' -d '{ "pullRequest": 17, "expectedRevision": 4 }'
When the working pull request closes unmerged, the card falls back to its first trusted open pull request (else a trusted merged one), never an outsider's.
Card-move rules can send a card to another board. A route that moves existing cards can set
moveToBoardKeyto send the card to a phase on another board. The card keeps its id, the old phase's sandbox stops and the target phase's runner starts.Rules test pull request trust separately.
item.trustedreplacesauthor.trusted(rules saved with the old name still work), and the newpullRequest.trustedtests the event's pull request author, or the author of the card's working pull request.{ "field": "pullRequest.trusted", "operator": "equals", "value": true }Breaking:
newestOpenPullRequestNumberis no longer exported from@mastra/factory/boards. UseworkingPullRequest(item)withpullRequestSourceNumberto get the pull request a card works on:import { pullRequestSourceNumber, workingPullRequest } from '@mastra/factory/boards'; const working = workingPullRequest(card); const number = working ? pullRequestSourceNumber(working) : undefined;
-
Added opt-in health metrics to Factory, sent through
mastra.metrics. Pick the groups you want, since every record counts towards observability usage: (#30225)new MastraFactory({ // ... metrics: { groups: ['process', 'postgres', 'redis', 'sandbox', 'intake'] }, // or 'all' });
Or set
FACTORY_METRICS=all(or a list likesandbox,intake).FACTORY_METRICS_INTERVAL_MS(default 60s, minimum 15s) andFACTORY_METRICS_MAX_PER_MIN(default 500) tune how often records are sent and cap their volume. Metrics are namedmastra_factory_*and labeled withservice(api,workerorall) so split deployments can be told apart. -
Added intake order: each board now owns its intake rules (up to 100 per board), and a project keeps a separate order in which its boards are asked to take a new item. Under the new evaluator an item no board's rules take is recorded as Not routed instead of landing on a default board, and an admin can route it again once a rule is fixed. (#30370)
Which projects use it
Projects created from this release on use the new evaluator. Existing projects keep the old one until an admin switches them:
mastra api factory intake-order set <project-id> '{"evaluator":"intake-order"}'
To force one evaluator on every project (for a rollout or tests), set the
intakeoption orFACTORY_INTAKE_EVALUATOR(intake-orderorroute-list) the same on every replica:const factory = new MastraFactory({ intake: { evaluator: 'intake-order' }, });
A project falls back to the old evaluator only when its setting was read and is empty; while it can't be read, arrivals wait and retry and a card created without a board is refused with
intake_board_required.During a rolling deploy, replicas still on an older release decide every project by the old evaluator, so a new project's items can be routed that way until all replicas run this release.
Before you switch
Factory derives each project's intake order from its current rules, and follows your rule edits until you set the order yourself.
GET /web/factory/projects/:id/intake-orderruns both evaluators over the newest 200 items against the order in force and reports how many would land on a different board and how many no board would take, so you can fix rules first.Also new
PUT /web/factory/projects/:id/intake-ordersets the order, the project's evaluator, or both;GETreports the evaluator in use and where it came from (evaluatorSource).GET /web/factory/projects/:id/intake/not-routedlists items no board took, oldest first, a page at a time (limit,cursor);POST .../intake/not-routed/:decisionId/route-againfiles one by intake order once a rule takes it.- Intake rules can be listed and reordered per board with
boardKey. - Deleting a board deletes its intake rules, each audited.
- Under the new evaluator, a card created without a board that no board takes is refused with
intake_board_required(thefactory_create_work_itemtool now accepts aboardfor this), and moving a rule to another board is refused withintake_route_board_fixed.
-
Added
GET /web/factory/projects/:id/intake/skipped. For each card-move rule that matched an event but was skipped because its target couldn't take the card, it returns how often that happened in the last 30 days and the newest skip. (#30507)Also added
mastra api factory intake skipped <project-id>to read the same counts from the CLI. -
A person's reply no longer waits behind automated runs. When a trusted collaborator comments on, or reviews, a card's GitHub pull request or issue, the session wakes even while automated runs hold every run slot. Each server process keeps 2 slots for these replies on top of
dispatcher.maxInFlight, claims them first, and lets them borrow a free automated slot. Bot accounts, untrusted authors, Factory's own comments and activity from other sources still wait as automated runs. (#30307)Change the reserve with
dispatcher.maxInteractiveInFlight(orMASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT);0keeps no reserve:const factory = new MastraFactory({ storage, dispatcher: { maxInFlight: 10, maxInteractiveInFlight: 2 }, });
With the defaults a process holds up to 12 run slots.
GET /web/factory/projects/:id/run-queueadds alaneto each run,queuedByLane, andslots.interactive, and lists waiting replies before automated runs. A run'spositionnow counts within its lane, so a waiting reply and the oldest automated run are both1. The other fields keep their meaning;slots.inUsecounts automated slots, including any a reply borrowed.GitHub rule actors now carry
human: truewhen GitHub reports the sender as a user. -
Added personal custom providers. A custom OpenAI-compatible endpoint is now saved either for yourself or for your organization, the same way provider API keys are. (#29879)
- Personal endpoints are visible only to you and are used by your personal sessions.
- Organization endpoints are used by work that runs on the organization's credentials. Adding, editing or removing one now requires an organization admin.
- Custom endpoints are added from the Add provider dialog and listed with the other providers. The separate "Custom providers" section is gone.
- Editing an endpoint without retyping its API key keeps the saved key, as long as the URL stays on the same host. Moving it to another host asks for the key again.
- Adding an endpoint under a name that is already in use is refused instead of replacing the existing one. So are names reserved for a built-in provider, its sign-in, or the Mastra Gateway (for example "OpenAI", "OpenAI Codex" or "Mastra Gateway").
- A Factory hosted on the Mastra platform only calls custom endpoints at a public HTTPS address. Saving one on plain HTTP,
localhost, a private network or the cloud metadata address is refused with a message explaining why. Local and self-hosted Factories can still use endpoints on their own machine or network, such as Ollama or vLLM.
Before you upgrade
- Organization endpoints no longer apply to personal sessions. Add the endpoint again as a personal one to keep using it there.
- On a hosted Factory, endpoints saved earlier on a local or plain-HTTP address are marked "URL not allowed" and their models are no longer offered. Edit them to a public HTTPS address.
- Review your organization's endpoints. One named like a built-in provider (for example "OpenAI") still takes over that provider's models; remove it or rename it.
The custom provider routes take a
scope(userby default, ororg). Saving withpreviousIdedits that provider; saving without it adds one:POST /web/config/custom-providers { "name": "My gateway", "url": "https://llm.example.com/v1", "models": ["my-model"], "scope": "org" } DELETE /web/config/custom-providers/my-gateway?scope=org
-
Lower default run cap (#30295)
A Factory server now runs at most 10 automated agent runs at once, down from 25. Runs past the cap wait their turn instead of all starting together. Raise the cap with
dispatcher.maxInFlight, or theMASTRACODE_DISPATCH_MAX_IN_FLIGHTenvironment variable on a deployed server. The cap applies to each server process, not to the whole deployment.new MastraFactory({ storage, dispatcher: { maxInFlight: 25 }, });
See the run queue on the board
The board now shows how many automated runs are waiting for a free slot. Click the indicator to see each waiting automated run, oldest first, with its card, and open the card from the list. A waiting card says
Queued (#3)instead ofStarting an automated run…. The list and card positions cover the oldest 50 waiting runs; the count always includes every one. The same data is available fromGET /web/factory/projects/:id/run-queue. -
Intake rules can now set a description on the cards they create, so cards from integrations show the item's details instead of an empty description. (#30253)
return { type: 'upsertLinkedWorkItem', board: context.intake.board, source: 'github-dependabot-alert', sourceKey: alert.id, title: alert.title, description: alert.description, url: alert.url, stage: context.intake.initialPhase, // ... };
-
Work Intake: what you select is what comes in. (#30625)
-
One list per service, no sync switches. Settings → Work Intake lists each connected service with its selected sources and an Add account button. A service with nothing selected brings in nothing. Dependabot alerts keep their own switch.
-
GitHub issues follow the list. New GitHub issues become cards only for repositories in the GitHub list. Pull requests still come from every linked repository. On upgrade, every repository already linked to a Factory is added to the list once, so nothing stops arriving. Linking a repository adds it to the list unless the request sends
selectIntake: false, and adding a repository to the list brings in its open issues.
To link a repository without bringing in its issues:POST /web/factory/projects/:projectId/source-control-connections/:connectionId/repositories { "repository": { "externalId": "99", "slug": "acme/app" }, "selectIntake": false }
-
Vanta follows its selection. Vulnerabilities sync only while the Vanta source is selected. Organizations whose Vanta sync was on with nothing selected get the source selected once on upgrade.
-
Routing has its own page. The intake order and the Not routed list moved from Settings to Routing in board settings.
-
-
Added Vanta vulnerabilities as a Factory intake source through MastraConnect. Once you connect Vanta and enable it in intake settings, each active vulnerability becomes a card labeled
securitywith its severity, package, and remediation date in the description. (#30255) -
Intake integrations are now off until you turn them on. A newly connected integration no longer starts pulling items onto your boards until you enable it in the intake settings. (#30251)
-
Added two reads that serve a Factory board without sending every card.
GET /web/factory/projects/:id/boards/:boardKey/phasesreturns, for each phase of the board, how many cards it holds and the first of them in the order asked, after the search and filters given.GET /web/factory/projects/:id/work-items/filter-optionsreturns the labels and people the board can be filtered by.item=<card id>also answers for one card and its place in each phase, however deep it lies, without listing the phase down to it. Each card is named with aversionof its body, which?workItemId=also sends, so a reader keeps the bodies it holds and reads only the ones that changed. (#30177)const res = await fetch(`/web/factory/projects/${projectId}/boards/work/phases?label=bug&limit=10&cards=true`); const { phases, matchingTotal, boardTotal, workItems } = await res.json(); // phases: [{ phase: "intake", total: 42, cards: [{ id, version }, …] }, …]
-
Removed the
intake.evaluatoroption fromMastraFactory. New projects already use the intake order, so the option only mattered for older projects. (#30676)MastraFactoryno longer acceptsintake: { evaluator }, and throws at startup when it is passed.GET /web/factory/projects/:id/intake-orderno longer reportsevaluatorSource: 'option'; it reportsenv,project, orlegacy.
Upgrading
Set the evaluator with the environment variable instead, the same on every replica:
// Before new MastraFactory({ storage, intake: { evaluator: 'route-list' } }); // After: FACTORY_INTAKE_EVALUATOR=route-list in the environment new MastraFactory({ storage });
Or switch one older project at a time:
mastra api factory intake-order set <project-id> '{"evaluator":"intake-order"}'. Code that readevaluatorSource: 'option'should treatenvas the forced case. -
Factory takes an optional
coAuthorfor the commit co-author its agent sessions write. Omitted, nothing changes and sessions keep the Mastra platform bot identity; pass{ name, email }to credit your own bot instead. A field left out falls back to the default for that field. (#30485) -
Added a dry run and a "Where would this go?" tester for intake rules. A rule that never fires because an earlier board takes everything it would match now shows up with evidence, before it files anything. (#30380)
Dry run
POST /web/factory/projects/:id/intake/dry-runruns the intake rules over the project's newest 200 items, from what Factory already stored about them, and reports per board and per rule what it would take, what it would lose to an earlier board, and how many cards it actually filed in the last 30 days. Pass unsavedboardsrules or an unsavedorderto preview an edit: the response also says how many items would land somewhere else.Tester
POST /web/factory/projects/:id/intake/testtakes one item, byurlor by theitemIdof a recent card or Not routed item, and shows which board takes it and what every rule answered, including the condition each rule failed on and the item's value. A URL Factory hasn't seen is read once from a GitHub repository or GitLab project linked to the project; others are refused withnot_linked.On a card, the tester also replays its recent status events, and one
eventpassed in the request, through its board's card-move rules, and says for each whether the card moves, stays or is left to the integration, with every rule's answer. The dispatcher moves cards with the same code.{ "itemId": "<card-id>", "event": { "type": "work_item.updated", "labels": { "added": ["ship"], "removed": [] } } }Neither request files a card, records a decision or writes to a provider. Both run the intake order evaluator's own code, so they answer exactly what filing under intake order would.
-
Fixed Factory server memory growing with every session it ever opened. Factory now unloads a session from server memory when it stops the session's sandbox (a card leaving a phase's context or finishing), and after 30 minutes without activity. Sessions that are running, waiting on an approval or answer, open in a browser tab, or running a background process in their sandbox stay loaded. Unloading keeps the thread, its messages, the session row and the sandbox, and the session's next message, run, wake or opened tab loads it again. Without
auth, a deferred wake for an unloaded session waits until something else loads it, as it does after a restart. (#30612)Change the timeout with
idleSessionUnload, or passfalseto keep every session loaded:const factory = new MastraFactory({ storage, idleSessionUnload: { idleMs: 60 * 60_000, sweepIntervalMs: 5 * 60_000 }, });
-
Removed the unused
sandboxProviderfield from linked project repositories. Factory always uses the sandbox you configure, so the stored value was never read, and the GitHub and GitLab repository listings only ever filled it withcustomornone. (#30508)- Linking or updating a project repository no longer accepts
sandboxProvider, and project repository responses no longer include it. - The GitHub and GitLab repository listings used during setup no longer include
sandboxProvider. - New factories no longer create the
sandbox_providercolumn. Existing factories keep the column and its stored values, and Factory simply stops writing it.
Upgrading
Stop passing
sandboxProviderwhen linking a project repository:// Before await github.projectRepositories.link({ orgId, connectionId, repositoryId, sandboxProvider: 'local' }); // After await github.projectRepositories.link({ orgId, connectionId, repositoryId });
Update
mastratogether with@mastra/factory. The Factory UI ships withmastra, and repository linking fails when one of the two is older than the other. - Linking or updating a project repository no longer accepts
-
Asking a Factory session to work on a card now goes through the board, the way the board's own buttons do. Before, asking a Slack or web session to "review" a pull request that already had a card often ended in a side session posting its review in the chat, while the card's own review waited for approval. (#30628)
factory_transition_work_itemtakesrerun: trueto run the stage a card is already in again, as the board's Start button does. The run counts as approved by the person asking, and a busy card is refused as on the board. A rerun needs a person in the turn. Withoutrerun, a request for the card's own stage changes nothing and says whether its run is waiting for approval. The result now includes the card'surl.- Asking for a side session still starts one. The tools now steer a plain "review this pull request" to the pull request's card, and keep side sessions for what people ask to run in one and for work no stage does, such as pushing fixes to a pull request.
- Every tool that takes a work item also accepts the issue or pull request it tracks: its link,
owner/repo#12,group/project!7, or a tracker key such asENG-42. With several repositories linked, the link finds the right card where a bare#12might not.factory_list_work_itemstakes the same references as its query. factory_inspect_work_itemlists the card's stage, whether it can run again, and the stages its board lets it move to next.factory_start_sessiononly starts side sessions. ItsworkItemandroleinputs are removed: they started a card's role without the board's rules, such as which stage the card is in and whether it is busy.
-
Added Dependabot alerts as a Factory intake source. Turn on Sync alerts under GitHub in intake settings and pick repositories, or
PUT /web/intake/configwith{ "dependabot": { "enabled": true, "sourceIds": ["owner/repo"] } }. Open alerts in those repositories become cards labeledsecuritywith the advisory details as the description, and they close automatically when the alert is fixed or dismissed. (#30254) -
Changing an intake route now warns you when cards already on your boards match a different board, and offers to move those untouched cards to the start of their new board. (#30252)
-
Added two reads that serve the sidebar's sessions without sending every session and every card holding one.
GET /web/factory/projects/:id/session-rowsreturns one view of a project's sessions as rows, sorted, grouped and filtered on the server, with the first five rows of each group and how many each group holds. A card's sessions come back as one row carrying the card, its pull or merge request and its status.GET /web/factory/projects/:id/session-activityreturns which sessions are running, waiting on a person or still coming up. Both answer304when nothing changed. (#30473)A project's session list is now kept in memory and read from the database again only when a session was added, removed or changed. Each request first checks a count and the newest row instead of reading every session.
const res = await fetch( `/web/factory/projects/${projectId}/session-rows?groupBy=board&owner=mine&window=board:work:25`, ); const { groups, matching } = await res.json(); // groups: [{ key: "board:work", total: 42, rows: [{ session, status, card, pullRequest, … }, …] }, …]
-
Factory no longer asks you to pick a repository before a card starts working. A card that names no repository starts in the Factory environment's first repository; the agent works out from the card which of the sandbox's repositories it belongs to, works there, and the card records that repository with the run's first push or pull request. Cards that already name a repository start there as before. (#30506)
Because nothing is left to choose, a run start no longer fails with
repository_ambiguous(its 409 response no longer carriescandidates), andfactory_list_attentionno longer returnsneedsRepositoryorlinkedRepositories. -
Board routes can now move cards when labels or assignees change, and when a pull request is reopened. (#30373)
Two event families —
work_item.*events are about issues; every pull or merge request event ispull_request.*. A route onwork_item.openedfiles new issues, and a route onpull_request.openedfiles new pull requests with no card (and moves an issue's card when its pull request opens).work_item.createdkeeps its meaning: it files new issues and new pull requests alike, so existing routes, and routes created withouton, behave as before. New projects get their pull request routes onpull_request.opened. Apull_request.openedroute stored by an earlier version still only moves cards, through every edit (the API marks itpullRequestOpenedMovesOnly: true); add a route to file pull requests.New events —
work_item.updatedfires when an issue's labels or assignees change, andpull_request.updatedwhen a pull request's do, on its own card or an issue card it is attached to;pull_request.reopenedmoves a card only where a route names it. A reopened pull request with no card is filed like a new one, and a pull request no board took (Not routed) is filed once a label or assignee change makes a board's rule match.New filters —
event.labels.added,event.labels.removed,event.assignees.added,event.assignees.removed,card.phase,item.hasPullRequestanditem.hasIssue.Behavior — changes the card's own session makes are held until its run ends and combined into one event. Changes people make are evaluated after about five seconds, with a burst combined into its net change; like every route move, a move into a phase that isn't terminal still waits for a run in flight. A move made by a rule never triggers an update. A reopened GitHub or GitLab issue with no card is now filed like a new one.
{ "on": ["work_item.updated"], "when": { "operator": "AND", "conditions": [{ "field": "event.labels.added", "operator": "contains", "value": "ship" }] }, "target": { "boardKey": "work", "phaseKey": "done" } }
Patch Changes
-
Stopped the Mastra platform GitHub event poll from reading the Factory database every 20 seconds. (#30257)
-
Recognize Detail findings as linked work items so intake cards retain their external source and rule identity. (#30410)
-
incident.io boards in Factory no longer create cards while a list loads. (#30271)
-
Pull request review status comments now say why a review attempt failed, without exposing private details. (#30687)
-
The incident.io sweep no longer re-runs rules for follow-ups it already handled, and one follow-up that fails no longer stops the rest of its page from getting cards. (#30378)
-
Fixed pull request reviews that recorded the same verdict over and over without finishing. (#30559)
-
Factory card links that agents post (in Slack threads, GitHub comments and tool results) now open the card's session directly, the same as clicking the card on its board. (#30666)
-
Added
GET /web/factory/projects/:id/work-items/:workItemId/session-repository. (#30609) -
Fixed board listing revalidation to use SHA-256, so a changed board is not treated as unchanged. (#30596)
-
Card-move rules now decide for themselves whether they act on pull requests from outside authors. (#30623)
-
The Activity sort in the Factory sidebar now orders sessions that share a status by their last update instead of their creation date, the same as Last updated does. (#30656)
-
Fixed reopened pull request review sessions loading the pull request's AGENTS.md and CLAUDE.md as trusted instructions. (#30612)
-
New Factory databases no longer get the tables that only existed to migrate data from older releases (pre-split cards, the split progress marker, per-member intake settings, the original intake source bindings and their migration log). (#30488)
-
Factory sessions now tell the agent that a directory's AGENTS.md only loads when it opens files there with
viewor an edit tool, and ask it to read the applicable AGENTS.md files before its first change in a directory, including when it works through shell commands. (#30678) -
Fixed Factory plan previews when the plan file lives inside a repository checkout in a multi-repository session. (#30436)
-
Settings › Tools can now list each Mastra Connect connection's tools. (#30610)
-
Fixed Settings › Tools saying Mastra Connect tools are off when a Factory sets the
toolsoption, even when that option uses Connect tools (#30579). (#30607) -
Fixed the Factory chat showing the same tool call twice, such as two identical plan cards with their own Approve and Reject buttons. (#30214)
-
Intake rules that file new cards can now target any non-terminal phase of their board, not just phases the board's first phase can move to. (#30620)
-
Factory onboarding's Work step now lists the GitHub repository or GitLab project chosen in the first step as an issue source, switched on by default. (#30273)
-
Fixed who owns the sessions a Factory card runs in, and who can approve what they wait on. (#30146)
-
Fixed a pull request Factory opened for a card whose issue lives in Jira, Linear or incident.io getting a card of its own on GitHub. (#30418)
-
Fixed reopened pull requests showing as closed in Factory. (#30388)
-
Fixed the repository picker failing with "Failed to list repos (500)" for GitHub accounts with hundreds of repositories. (#30345)
-
Removed Factory server routes that nothing calls anymore. (#30489)
-
Allow Factory hosts to pass
scorersto the mounted Mastra Code agent. (#30363) -
A Factory whose server already has a Mastra Gateway key, such as the one the Mastra platform adds to a deploy, now shows the gateway as connected and no longer offers the "Connect Mastra Gateway" button. (#30193)
-
Deliver Factory notifications when their bound session no longer exists, including concurrent notifications. (#30422)
-
Added a file index for a session's workspace, so Go to file in the session panel finds any file the file tree can open by name, not only files in folders already opened. (#30388)
-
Added
mastra api factory intake dry-runandmastra api factory intake testto check a Factory project's intake rules against real items without filing anything. (#30380) -
Reduced the work the Factory server does to keep the session sidebar and board up to date, and fixed session latency timestamps on LibSQL. (#30648)
-
Factory agents can now resolve and reopen GitHub pull request review threads with
source_control_resolve_diff_thread. (#30671) -
A person can no longer move a busy Factory card into a phase that starts a run. (#30513)
-
Fixed slow Linear boards in Factory. (#29998)
-
Fixed slow reading of the pull request number from GitHub card keys that contain very long runs of digits. (#30577)
-
New, renamed and hidden sessions now show up in teammates' sidebars right away, instead of after up to a minute, and the sidebar no longer polls while a session starts. (#30617)
-
GitLab boards in Factory no longer create cards while a list loads. (#30265)
-
When the observational memory model fails (rejected model, quota, credentials, rate limit, context limit or provider outage), the error now tells you to change the memory model in Memory settings and offers a "Change memory model" action that opens them, in both the Factory chat and Slack. (#30702)
-
Fixed Vanta intake appearing automatically when Platform credentials are configured. (#30284)
-
Fixed Factory sessions being cut off from a card they were still working on. (#30608)
-
Stopped Factory's background issue sweeps from reading the database when nothing changed. (#30267)
-
Fixed deleting an intake rule being slow on remote databases and breaking other open rule edits. (#30613)
-
Simplified
mastra factory devstartup output. (#30344) -
Jira boards in Factory open faster and no longer create cards while a list loads. (#30270)
-
Fixed pull requests Factory opened from an issue card also showing up in Intake as new items. (#30337)
-
Sandboxes in a Factory with more than ten repositories can now reach all of them with
gitandgh. (#30121) -
The "Manage in Mastra Platform" button under Settings → Mastra Connect tools now opens the Connect settings of the Factory's Platform project, instead of the Platform home page. (#30262)
-
source_control_push_branchnow reports what it pushed. (#30700) -
Approving a held Factory run with
factory_resolve_proposal, or retrying a failed one withfactory_retry_decision, now makes the session follow the run's card, as moving the card already did. (#30637) -
Fixed board cards showing a different session status than the sidebar. (#30624)
-
Fixed Factory starting a card's session in a repository the card doesn't come from. (#30609)
-
Improved sidebar performance in projects with many sessions. (#30616)
-
Fixed the session status in Factory's sidebar and board. (#30627)
-
Fixed Vanta sync closing every filed vulnerability card when Vanta is not connected. (#30289)
-
Fixed GitHub pull request cards losing their labels, so intake routes that match on labels (for example
security) now route pull requests too. (#30250) -
Fixed a pull request getting two review verdicts on the same commit. (#30691)
@mastra/github-signals@0.5.3
Patch Changes
- Fixed delivery of authorized review comments and inline findings even when bot summaries change or check status is unknown. (#30246)
@mastra/google-cloud-pubsub@1.1.8
Patch Changes
GoogleCloudPubSubnow reportsredeliversUnackedastrue: a message a dead subscriber held is delivered again once its ack deadline passes. (#30279)
@mastra/inngest@1.11.3
Patch Changes
-
Preserved Inngest execution when an HTTP observer disconnects by explicitly advertising detached streaming, even when the wrapped Agent has streams disabled. (#30229)
-
Inngest workflow and durable agent runs that Inngest gives up on are now marked
failedin storage. (#30698)
@mastra/json-render@0.1.0
Minor Changes
-
Added
@mastra/json-render, which lets agents compose json-render interfaces from your component catalog. (#29914)import { JsonRenderProcessor } from '@mastra/json-render'; const ui = new JsonRenderProcessor({ catalog }); const agent = new Agent({ id: 'ui-agent', name: 'UI Agent', model: 'openai/gpt-6.1-sol', instructions: catalog.prompt({ mode: 'inline', editModes: ['patch'] }), inputProcessors: [ui], outputProcessors: [ui], maxProcessorRetries: 2, memory: new Memory(), });
- Interfaces the model writes stream to the client as
data-specparts, and the reply's text keeps only the prose. Render them withuseJsonRenderMessage()from@json-render/react. - Interfaces are saved with the message, so they render again after a reload.
- Later turns can edit the latest interface with a few patches. Send the interface's state under the
JSON_RENDER_STATErequest context key, and the model sees what the user set and the edit keeps it. - Interfaces that don't match the catalog are sent back to the model to fix before they're saved.
- Interfaces the model writes stream to the client as
@mastra/langfuse@1.7.0
Minor Changes
- Updated to the OpenTelemetry semantic conventions 1.41.0 attributes from
@mastra/otel-exporter. Agent runs with tools now show the tool list in Langfuse. The input of the agent observation is now{ "prompt": "...", "tools": [...] }instead of plain text. Update evaluators or datasets that read this input as plain text. (#30342)
Patch Changes
- Fixed a crash on import after a fresh
npm install @mastra/langfuse. npm installed OpenTelemetry exporters that did not match the rest of the package, and the import failed withThe requested module '@opentelemetry/api' does not provide an export named 'SeverityNumber'. (#30689)
@mastra/libsql@1.31.0
Minor Changes
-
Runs stored with the experimental workflow
storageVersion: 2option can now be written by several workers at once, as evented workflows andcreateEventedAgentdo. Concurrentforeachiterations all save their results, and the store writes a full copy of the workflow state after 100 changes so loading a long run stays fast. (#29370)If you stored version 2 runs with
@mastra/pg1.36.0-alpha.0 or@mastra/libsql1.30.0-alpha.0, the store adds the columns this needs to themastra_workflow_runstable on startup, and those runs keep working.Also in: @mastra/pg@1.37.0
Patch Changes
-
Fixed thread state writes failing with
SQLITE_BUSYwhile another write is in progress on a local database file. (#30281) -
Fixed factory storage on existing databases after a column is removed from a collection schema. (#30495)
Also in: @mastra/pg@1.37.0
-
Fixed workers failing to start when several of them upgrade the same libSQL database at once. (#29370)
-
Fixed background task updates and deletes on a local LibSQL file database stalling for up to five seconds (and sometimes failing with
SQLITE_BUSY: database is locked) when they ran alongside workflow run writes, for example while shutting down Mastra with background tasks still running. (#30504) -
Listing workflow runs with
summary: truenow also returnsparentWorkflow: { workflowId, runId }for nested runs, next tostatusandtimestamp(#28712). (#30274)Also in: @mastra/pg@1.37.0
@mastra/mcp@2.10.0
Minor Changes
-
Added
appsRequireClientSupporttoMCPServer. When enabled, MCP Apps are served only to clients that declare MCP Apps support; other clients see the server as if it had no apps (noui://resources, no app links on tools or results, and no app-only tools). This also works for 2025-era clients over stateless HTTP: a client that declares support atinitializegets anMcp-Session-Idthat carries the declaration on its later requests. (#30244)const server = new MCPServer({ name: 'My server', version: '1.0.0', tools, appResources: { 'ui://my-app': myApp }, appsRequireClientSupport: true, });
Tool result
transformfunctions now also receiveappsin their context:truewhen the calling client renders MCP Apps, so a transform can send a short summary to the model and the full data to the app asstructuredContent. -
MCPServeraccepts amaxRequestBodySizeoption, so HTTP requests larger than the 4 MiB default are no longer answered with a413before the tool runs. (#30411)// Before: a tools/call body over 4 MiB was rejected // { "code": -32000, "message": "Payload Too Large: Request body must not exceed 4194304 bytes" } // After: raise the limit for the servers that need it const server = new MCPServer({ name: 'intake', version: '1.0.0', maxRequestBodySize: 16 * 1024 * 1024, tools: { submitIntake }, });
The bound is in bytes and must be positive. Leaving it unset keeps the SDK default of
4194304(4 MiB), and a body over the limit is still rejected with a413JSON-RPC error before it is parsed. It covers only a body the server reads itself: if body-parsing middleware supplies the parsed body, the bound does not apply, so raise the size limit on that parser too. It applies tostartHTTPrequests only;stdiohas no request bodies.
@mastra/mcp-apps-components@0.2.0
Minor Changes
-
Added two MCP Apps built from Studio's observability pages, served by the built-in MCP server through its observability tools: (#30244)
- Trace viewer (
@mastra/mcp-apps-components/trace-viewer): draws a trace on Studio's timeline and opens each span's details. - Observability explorer (
@mastra/mcp-apps-components/observability-explorer): Studio's Traces, Spans, Threads, Logs, and Metrics pages as tabs, with filters, time range, sort, paging, and drilldowns from metrics into traces or logs. Selecting a row opens it on the timeline. The model's query filters show up as filter-bar chips; conditions the bar can't represent stay applied and are listed above the list. The Metrics tab opens on the time range and filters of theanalyze_metricscall that opened it, and names any filters the dashboard can't apply.
Both apps work with the conversation in hosts that support it. They tell the model which trace, span, filters, or log are open. Ask about this buttons on a trace, span, or log send a message about it, and the apps have a Fullscreen button and, when the server sends Studio's URL, an Open in Studio button. Apps also report the package version to the host when they connect.
To serve them from your own
MCPServer, register them as app resources:import { MCPServer } from '@mastra/mcp'; import { traceViewerApp } from '@mastra/mcp-apps-components/trace-viewer'; const server = new MCPServer({ name: 'my-server', version: '1.0.0', tools, appResources: { 'ui://mastra/trace-viewer': traceViewerApp }, });
- Trace viewer (
Patch Changes
-
Interface icons now use Central's Medium chevrons, which match the size of the icons around them, and one consistent shape for speech bubbles (Chat Bubble 7), thumbs up and down, and the settings gear. (#30523)
Also in: @mastra/playground-ui@70.0.0
-
Fixed the observability dashboard widget briefly drawing in the dark theme inside a light-themed host. (#30500)
-
Interface icons in MCP app components now use Central Icons. (#30438)
@mastra/memory@1.41.2
Patch Changes
-
recall()now only returns messages from the requested thread or resource, even if the vector store returns results outside its filter or labels them with the wrong thread or resource. (#30446) -
Fixed Observational Memory crashing when capped history rendering encounters a message text part without text. (#30272)
-
Fixed the experimental vNext working memory tool letting one thread erase memory shared with other threads. (#30306)
-
Improved token counting in long Observational Memory tool runs by removing redundant serialization of plain JSON tool results. (#30400)
-
Fixed semantic recall re-embedding the same text on every save. (#30429)
-
Fixed Observational Memory losing every message for agents that use a
mastra/gateway model with a Gateway organization key. (#30414)
@mastra/mongodb@1.27.1
Patch Changes
- Fixed startup cleanup leaving an extra observational memory record live. (#30452)
@mastra/observability@1.24.1
Patch Changes
-
Clamp reversed live span timestamps to zero duration so exporters receive completion events. (#30293)
-
Fixed
strategy: 'realtime'onMastraStorageExporterin apps with durable execution. (#29566) -
Fixed the storage exporter dropping a span end that reached storage before the span's create row. (#29274)
-
Stop deep-copying span metadata twice for every logger and metrics context. (#30679)
@mastra/otel-bridge@1.6.0
Minor Changes
- Spans now use the OpenTelemetry semantic conventions 1.41.0 attributes from
@mastra/otel-exporter. See the@mastra/otel-exporterchangelog for the attribute changes. (#30342)
Patch Changes
- Fixed Mastra logs being dropped by
OtelBridgein apps on OpenTelemetry JS SDK 3. (#30546)
@mastra/otel-exporter@1.6.0
Minor Changes
-
OTLP traces and logs now declare OpenTelemetry semantic conventions 1.41.0 with a schema URL. Backends that read attributes by version now read the GenAI attributes correctly, including the cache token counts. No configuration is needed. Traces sent through a custom
exporterdeclare no version, because that exporter can change the attributes. (#30342)Other attribute changes that follow 1.41.0:
- Reasoning tokens now use
gen_ai.usage.reasoning.output_tokens. Update any queries or dashboards that usegen_ai.usage.reasoning_tokens. gen_ai.tool.definitionsis now a list of{ type, name }objects instead of a list of tool names.gen_ai.system_instructionsis now a list of text parts, such as[{"type":"text","content":"..."}], instead of plain text.- Each message in
gen_ai.output.messagesnow has afinish_reason. The reason isunknownwhen the model did not report one. gen_ai.request.stop_sequencesandgen_ai.response.finish_reasonsare now lists instead of JSON text.- Agent run spans now include
gen_ai.provider.name, and workflow run spans now includegen_ai.workflow.name. gen_ai.provider.namenow uses the OpenTelemetry provider names for AI SDK provider ids, such asopenaiforopenai.chatandgcp.vertex_aiforgoogle.vertex.chat.- If you create a
SpanConverteryourself, passformat: 'GenAI_v1_41_0'. The old'GenAI_v1_38_0'value no longer type-checks.
- Reasoning tokens now use
@mastra/pg@1.37.0
Patch Changes
- Fixed
PgVectorcalls failing with "Vector table ... does not exist" after an index was deleted withdeleteIndex()and created again while thatPgVectorinstance was still starting up. (#30578)
@mastra/pinecone@1.1.4
Patch Changes
- Fixed Pinecone queries ignoring the other conditions in a filter that also uses
$all. (#30468)
@mastra/platform@0.1.0
Minor Changes
-
Added
PlatformBrowser, a Stagehand browser backed by a Mastra Platform browser session. By default it provisions a session withPOST /v1/browsers/sessionson the Platform and connects to the returned CDP URL; passcdpUrlto connect to a session you already provisioned, with no token or API call. The access token falls back toMASTRA_PLATFORM_ACCESS_TOKEN/MASTRA_PLATFORM_SECRET_KEY, the project toMASTRA_PROJECT_ID, and the API URL toMASTRA_BROWSER_API_URL.@mastra/platformnow depends on@mastra/stagehandat runtime. (#29428)import { PlatformBrowser } from '@mastra/platform'; const agent = new Agent({ name: 'browser-agent', model, browser: new PlatformBrowser() });
-
Added
@mastra/platform: hosted Mastra Platform Memory and Knowledge clients, with Platform Sandbox and Filesystem re-exported from@mastra/platform-workspace.PlatformMemoryis a drop-inmemoryforAgentthat loads observations and recent messages from a Platform Memory instance and saves each turn back; observation and reflection run on the Platform.PlatformMemoryClientexposes the same API directly. Credentials fall back toMASTRA_PLATFORM_ACCESS_TOKEN/MASTRA_PLATFORM_SECRET_KEY.PlatformMemoryusesMASTRA_MEMORY_INSTANCE_ID;PlatformKnowledgeusesMASTRA_KNOWLEDGE_INSTANCE_ID.PlatformKnowledgetakes every scope declaration and access rule from its instance, Memory's and Platform importers' included, and has noscopesoption. Agents read imported pages when their runs hold the scope an importer's rule grants (for nowimports:all). (#29428)import { PlatformMemory, PlatformKnowledge, PlatformSandbox, PlatformFilesystem } from '@mastra/platform'; const agent = new Agent({ name: 'assistant', model, memory: new PlatformMemory() });
Patch Changes
-
PlatformKnowledgenow supports listing pins:knowledge_pinwithkind: 'list'pins a page's listing on hosted Knowledge instead of refusing it as an old storage adapter. (#29428) -
PlatformMemoryfixes for read-only runs and working memory: (#29428)
@mastra/platform-workspace@1.13.1
Patch Changes
- Fixed commands with a
cwdthat doesn't exist failing as "Direct-exec transport failed … after 2 attempt(s)" in platform sandboxes. (#30260)
@mastra/playground-ui@70.0.0
Minor Changes
-
Central icons now draw at the size Lucide icons did. The icon sizes grow by 2px (
xs14px,sm16px,md18px,lg22px) because Central leaves more room around each drawing, so an icon in the same slot keeps the size people are used to. Product icons, the remaining Lucide icons, brand logos and product marks keep their drawn size. Avatars no longer borrow the icon sizes: thexsandinlineavatars use their own--spacing-avatar-xs(12px) and--spacing-avatar-inline(16px). (#30555)A few Central shapes that run edge to edge, such as plain arrows and the
•••dots, get an optical inset so they match the rest of the set, with their stroke thickened by the same factor so every icon keeps the same line weight. The inset lives incentral-icons.jsonand the icon generator applies it. -
Clicking a Knowledge page in the graph now shows a short peek with its link and note counts, a preview of the body, its connections and the latest note. The full page's side column adds On this page, built from the body's headings, and Connections, listing the pages it links to and the notes that mention it. (#30706)
-
Polished the shared sidebar so it looks the same in every app. (#30204)
- The sidebar is 232px wide by default (192px to 340px when dragged) and 60px collapsed. The defaults live in the component and
SIDEBAR_WIDTHSexports them; passminWidthonly when a view needs more room. - Rows sit 1px apart and 10px from the sidebar's edges, with 8px under the header. Groups sit 14px apart, with titles 4px above their rows, and the first group's title is kept for screen readers only.
- Filled product icons (Agent, Workflow, MCP Server) draw at the same size as the line icons beside them.
- The resize handle and the collapsed logo's toggle appear after a short hover delay, so passing over them doesn't flash them.
- The nav's scrollbar no longer stays on screen after you click a link, and expanding the sidebar onto an open sub-menu no longer moves focus to its Back button.
Sidebar.Meterkeeps one layout in both states. It acceptsloading, which shows the card at its loaded size, andrailValue, a shorter amount for the rail:<Sidebar.Meter label="Credits" value="$6,649.10" railValue="$7k" status="Auto top-up On" /> <Sidebar.Meter loading label="Credits" value="" status=" " />
- The sidebar is 232px wide by default (192px to 340px when dragged) and 60px collapsed. The defaults live in the component and
-
Opening a Knowledge page now shows it in a panel beside the Pages tree instead of replacing the graph, and the graph stops drawing while the page is open. The page's right column gains a Details list with its scope, last update, author, creation date and version. (#30588)
-
Added
unavailableReasontoModelPicker. When set, the picker shows its usual trigger, disabled, and hovering or focusing it shows the reason in a tooltip. Use it when the current user can see the model but is not allowed to change it. (#30471)<ModelPicker providers={providers} value={value} onValueChange={setValue} unavailableReason="Only the session owner can change the model." />
-
LogDataPanelaccepts anactionsprop to render extra controls in its header, next to the previous and next buttons. (#30244)<LogDataPanel {...panelProps} actions={<Button onClick={() => askAbout(log)}>Ask about this log</Button>} />
Fixed the Metrics page's model drilldown: clicking a model in the usage card now opens traces that used that model, instead of every trace in the time range.
-
InputGroupAddonnow insets its icon like a Button does (the group's--control-pxand--control-gap), so a leading or trailing icon in any field lines up with the icons of the controls beside it. A field built fromInputGroupparts by hand gets the same inset asSearchInput. An iconInputGroupButtonis now a chip inset in the field (8px shorter than it, with an even ring around it) instead of a full-height circle. (#30062)SearchInputis now plainInputGroupcomposition (a search icon, the input and a clear button) with no styling of its own. Its clear button keeps its space while hidden, so the field doesn't resize when text appears. It takes overListSearch's behaviour. It is either controlled (value, following every change the parent makes, such as a Reset or a URL change) or keeps its own text (defaultValue). Both modes acceptdebounceMs, which delaysonValueChangewhile typing; clearing reports right away.shortcutturns on the Cmd/Ctrl+Shift+F focus shortcut, andlistSearchPropsbundles a list page'ssize,debounceMsandshortcut.ListSearchandSearchFieldBlockare removed.Migrating
// Before <ListSearch onSearch={setSearch} label="Search agents" placeholder="Search by name" /> // After <SearchInput {...listSearchProps} onValueChange={setSearch} label="Search agents" placeholder="Search by name" />
ListSearch'sonSearch→onValueChange,value→defaultValue,shortcutDisabled→ leave outshortcut. It defaulted tosize="sm"and a 300ms debounce; pass them. To reset a field that keeps its own text, remount it with akey.SearchFieldBlock→SearchInput, inside aFieldwhen it needs a visible label.SearchInput'slabelis now the input'saria-labelinstead of a visually hidden<label>.
-
The dashboards entry point (
@mastra/playground-ui/domains/dashboards) now exports the schemas a widget is validated with, so an app that edits stored dashboard widgets can check its changes against the same rules the renderer uses. (#30298)- Options schemas for each built-in widget kind:
kpisOptionsSchema,kpiItemSchema,tableOptionsSchema,tableColumnOptionsSchema,timeseriesOptionsSchema,timeseriesSeriesSchemaandscoresOptionsSchema, with their types. - Value expression schemas and types:
valueExprSchema,valueRefSchema,queryRefSchema,ValueExpr,ValueRefandLabelledValue. - The allowed formats, colors and KPI icons:
VALUE_FORMATS,formatSchema,CHART_COLOR_NAMES,SERIES_COLORS,colorSchema,KPI_ICONS, and theValueFormat,ChartColorNameandKpiIcontypes.
import { kpisOptionsSchema, valueExprSchema } from '@mastra/playground-ui/domains/dashboards'; kpisOptionsSchema.parse({ items: [{ label: 'Runs', format: 'count', value: { query: 'runs' } }] });
- Options schemas for each built-in widget kind:
-
Added
FormLayout, the page frame for create and edit form pages. It shows a back link and the page title above a centered 640px column, lined up with each section title, with no breadcrumb bar. (#30715)import { FormLayout } from '@mastra/playground-ui/components/FormLayout'; <FormLayout backHref="/alerts" backLabel="Alerts" title="New alert" LinkComponent={Link}> <SettingsGroup>…</SettingsGroup> </FormLayout>;
-
On phones and tablets, the default sidebar (
mobileMode="takeover") now sits under the page instead of covering it. Opening it slides the whole page to the right, and the navigation underneath grows into place as it fades in, like the ChatGPT iOS app. While it moves, the page gets rounded corners, a thin edge and a soft shadow, so it reads as a card lifted above the navigation. (#30440)- Swipe the page right to open the sidebar and swipe left to close it. The page follows your finger. When you let go, it finishes in the direction you were last moving: a short swipe is enough, swiping back partway cancels, and a nudge of a few pixels springs back. It keeps the speed of your swipe and eases to a stop. Dragging moves only the page and the sidebar, so it stays smooth on long pages.
- While the sidebar is open, a faint tint of the opposite colour (light in dark mode, dark in light mode) covers the strip of page still in view, setting it apart from the navigation. Tap that strip, or press Escape, to close the sidebar. Focus returns to the menu button. Until then, Tab and Shift+Tab cycle through the sidebar, and the page and toasts behind it are out of reach.
- Swipes that start in content that scrolls sideways, or on sliders and other controls that handle their own drags, are left to that content.
- With reduced motion turned on, the sidebar opens and closes without sliding.
AppShellslides its content automatically. ASidebarrendered outsideAppShellhas no page to slide, so either move the page intoAppShellor keep the previous drawer:<AppShell sidebar={<Sidebar>{nav}</Sidebar>}>{page}</AppShell> // or, without AppShell <Sidebar mobileMode="drawer">{nav}</Sidebar>
On desktop, dragging the sidebar's edge no longer restyles the whole page on every move, so resizing stays smooth beside long pages. The live width is set on the sidebar panel itself, so
var(--sidebar-width)read outside the sidebar keeps the initial width. -
Switched
@mastra/playground-uicomponents from Lucide to Central Icons, and added Central Icons for your own UI. Each icon is its own module under@mastra/playground-ui/icons/central/and works insideIconlike any other icon. The icons are licensed under the Central Icons license, not Apache-2.0. SeeCENTRAL-ICONS-LICENSE.mdin the package. (#29934)import { Icon } from '@mastra/playground-ui/icons/Icon'; import { IconMagnifyingGlass } from '@mastra/playground-ui/icons/central/IconMagnifyingGlass'; <Icon size="sm"> <IconMagnifyingGlass /> </Icon>;
-
Add a “Contains text” filter to the span and trace explorers for backends that support indexed search. Histograms are hidden while search is applied. (#30299)
-
Added content filters with matching histograms for supporting hosts. (#30511)
-
Added
CardInset, a sunken panel for a list of rows inside aCardor a dialog. The panel pads each row and draws a divider between them, so plain elements andSettingsRows both work as rows. (#30699)<DialogBody> <CardInset> <div>Source</div> <div>Schedule</div> </CardInset> </DialogBody>
Removed
SectionCardandCardHeading. Build settings sections with the settings components instead:// Before <SectionCard title="Channels" description="Providers available to publish flows"> {rows} </SectionCard> // After <SettingsGroup> <SettingsTitle info="Providers available to publish flows">Channels</SettingsTitle> <SettingsContainer>{rows}</SettingsContainer> </SettingsGroup>
Patch Changes
-
Knowledge pages stay readable with long text: page descriptions and On this page headings are clamped, and search results show the matched text highlighted with a description line. (#30719)
-
Central Icons now cover every interface icon in Studio and Factory, and each icon family, such as speech bubbles, bells, folders and settings, uses one consistent shape. (#30438)
-
CodeDiffwith a file header now shows its lines flush against the header and the card's bottom edge, so stacked diffs in aCodeDiffListread like a pull request with no blank band above the first line or below the last. (#30668) -
Connect providers that use OAuth client credentials (
OAUTH2_CC) or no authentication (NONE) without leaving Studio. (#30336) -
Added the
playground-ui/icon-size-from-parentlint rule. (#30542) -
New feedback comments now show up in the list as soon as you submit them, instead of after the next refresh. (#30515)
Also in: @mastra/react@1.15.1
-
Knowledge search results now show the part of a page description that matches the query, instead of a first line that can hide it. (#30722)
-
CodeDiffnow paints its code on the card surface instead of the syntax theme's own background, so a diff matches the card around it in light and dark mode. (#30388) -
Sidebar.NavShowMoreaccepts arefto its button, so an app can move focus to it, for example when the other toggle disappears after a click. (#30475) -
Added two empty-state illustrations,
no-alertsandno-destinations, for pages that list alerts and their destinations. (#30354) -
Studio and Factory now use Central Icons for their interface icons. (#29934)
-
Fixed the right padding of
Sidebar.CommandHeader: its buttons now line up with the right edge of the nav rows below. (#30471) -
Fixed page scrolling getting stuck when the cursor is over a DataList. (#30333)
@mastra/rag@2.8.1
Patch Changes
- JSON chunking now keeps every character of a long string value when a field name or JSON escaping pushes split pieces over
maxSize, instead of silently dropping them. (#30407)
@mastra/redis-streams@0.9.0
Minor Changes
-
Added
createMonitorClient()andstreamKey()toRedisStreamsPubSub, so health checks can inspect Redis on their own connection instead of queueing behind event traffic: (#30225)const client = pubsub.createMonitorClient(); // unconnected; commands fail fast while disconnected await client.connect(); const groups = await client.xInfoGroups(pubsub.streamKey('workflows')); await client.destroy();
Patch Changes
-
RedisStreamsPubSubnow reportsredeliversUnackedastruewhile its reclaim loop runs (reclaimIntervalMsabove 0). (#30279) -
Fixed workflow runs that stayed
runningon Redis Streams when a worker shut down while one of their steps was still running. (#30387)
@mastra/sentry@1.3.0
Minor Changes
- Reasoning tokens now use
gen_ai.usage.reasoning.output_tokens, the name that Sentry reads.gen_ai.tool.definitionsis now a list of{ type, name }objects instead of a list of tool names.gen_ai.provider.namenow uses the OpenTelemetry provider names, such asopenaiforopenai.chat. Each message ingen_ai.output.messagesnow has afinish_reason. (#30342)
@mastra/server@1.84.0
Minor Changes
-
Removed unsupported experimental textSearch requests. (#30511)
-
The built-in MCP server now shows observability results as Studio views in clients that render MCP Apps, such as the Claude app: (#30244)
get_traceopens Studio's trace viewer: the timeline, with each span's details on click.query_traces,list_traces,list_logs, andanalyze_metricsopen Studio's observability explorer, with Traces, Spans, Threads, Logs, and Metrics tabs. The model's filters stay applied and show up as filter-bar chips the user can edit. Each tab appears only when the store keeps that data and the caller can use the tools that read it.- When an app shows a result, the model gets a compact text summary and the app gets the full rows as
structuredContent, cutting model context for these tools by roughly 5–8x.
Install
@mastra/mcp-apps-componentsto turn it on. Clients without MCP Apps support get the same tools and JSON results as before.npm install @mastra/mcp-apps-components
Two new
server.mcpoptions:apps: falseturns the apps off, andstudioUrlsets where the apps' Open in Studio button points. Undermastra dev,studioUrldefaults to the local Studio.export const mastra = new Mastra({ server: { mcp: { studioUrl: 'https://studio.example.com' }, }, });
Patch Changes
-
Fixed Gateway v2 deployments calling the Gateway v1 memory API. (#29445)
-
Reduced memory and CPU use when clients stream agent controller sessions. (#30615)
-
Preserved durable runs when an HTTP observer disconnects, including with older Inngest wrappers that do not explicitly advertise detached streaming. (#30229)
-
Workflow steps run by a standalone worker through the step-execution endpoint now follow the run's experimental
storageVersion, so a version 2 run reads step results and state the same way remotely as in-process. (#29370)
@mastra/turso@0.1.22
Patch Changes
- Raised the
@mastra/corepeer dependency floor to 1.84.0 to match the@mastra/libsqlversion it depends on. (#29370)
@mastra/valkey-streams@0.6.3
Patch Changes
-
Fixed workflow runs that stayed
runningon Valkey Streams when a worker shut down while one of their steps was still running. (#30387) -
ValkeyStreamsPubSubnow reportsredeliversUnackedastruewhile its reclaim loop runs (reclaimIntervalMsabove 0). (#30279)
Other updated packages
Dependency updates only: @mastra/agent-builder@1.2.2, @mastra/auth-better-auth@1.1.12, @mastra/braintrust@1.3.28, @mastra/datadog@1.4.23, @mastra/deepeval@0.1.25, @mastra/deployer@1.84.0, @mastra/deployer-cloud@1.84.0, @mastra/deployer-cloudflare@1.2.43, @mastra/deployer-netlify@1.2.43, @mastra/deployer-sandbox@0.3.28, @mastra/deployer-vercel@1.2.43, @mastra/e2b-desktop@0.1.14, @mastra/editor@0.17.2, @mastra/elysia@0.1.24, @mastra/express@1.5.28, @mastra/fastify@1.5.28, @mastra/hono@1.7.26, @mastra/koa@1.7.28, @mastra/langsmith@1.4.4, @mastra/longmemeval@1.1.43, @mastra/mcp-docs-server@1.3.14, @mastra/nestjs@0.3.1, @mastra/next@0.2.42, @mastra/opencode@0.1.43, @mastra/posthog@1.4.8, @mastra/tanstack-start@0.2.42, @mastra/temporal@0.6.1