github mastra-ai/mastra @mastra/core@1.84.0
November 17, 2026

one hour ago

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: $param now matches exactly one segment; raw : is no longer allowed inside a scope segment, requiring canonical encoding via encodeKnowledgeScopeId / decodeKnowledgeScopeId (existing data is not rewritten, so some scopes may become “new/empty” unless you update IDs).
  • @mastra/factory: newestOpenPullRequestNumber is no longer exported from @mastra/factory/boards; use workingPullRequest(item) + pullRequestSourceNumber.
  • @mastra/playground-ui: ListSearch and SearchFieldBlock are removed; migrate to SearchInput. Also removed SectionCard and CardHeading in favor of settings components.
  • @mastra/factory: MastraFactory no longer accepts intake: { 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 by LibSQLFactoryStorage and PgFactoryStorage; 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. Every recovery.workflowScanIntervalMs (60 seconds by default, give or take a fifth), it restarts the default-engine runs that stopped, by the same rule as restartAllActiveWorkflowRuns(). 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 and recovery.workflowGraceMs passed, 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() or shutdown() 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.workflows is '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/evented now accept the experimental storageVersion: 2 option. 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 an EventedAgent run 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, steps on a version 2 run's result is an async function, which onFinish and onError receive 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 redeliversUnacked getter, which defaults to false.

    With Redis or Valkey Streams, keep reclaimIdleMs at 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 EventEmitterPubSub or 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 running until you call restart() 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 maxStreamLength entries (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. Raise maxStreamLength if you run long steps with a high event volume.
    • A run whose message the broker dropped after maxDeliveryAttempts or inFlightTimeoutMs, 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 running or waiting run counts as stopped when no instance holds its run lease and neither the run nor that lease changed for recovery.workflowGraceMs (2 seconds by default). A run that stopped more recently is left to the workflow recovery loop that startWorkers() 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, within drainTimeout, 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 and knowledge.reindexLinks() repairs the rest.

  • Added knowledge.reembed() to embed Knowledge pages and notes that already exist, such as content written before vector and embedder were 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 $param in 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, so org:acme:viewer counted as an org:$orgId scope and its holder got that pattern's self rights there. (#30019)

    • Agent scopes are canonical addresses. An id containing :, /, # or % must be encoded with the new encodeKnowledgeScopeId. The raw form (e.g. org:a:b against org:$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:U123 becomes resource:slack%3AU123.
    • Patterns of one type with different segment counts no longer overlap, so org:$orgId and org:$orgId:viewer can be declared side by side.
    • decodeKnowledgeScopeId reads 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, so org:${encodeKnowledgeScopeId('a/b')} reaches rows stored from the raw org:a/b. Passing the old raw string unchanged does not: org:a/b is refused, and a raw scope that happened to contain an escape (org:a%3Ab, once stored as org:a%253Ab) now means the id a: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:viewer created under org:$orgId, once org:$orgId:viewer is declared) gets none of the new declaration's access. It is never a belongsTo parent, 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.
  • 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 after renameScopeDeclaration, 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:all then read every Linear connection's pages.

  • Added the apps and studioUrl options to ServerMCPConfig (server.mcp), for the built-in MCP server's MCP Apps. apps: false turns them off, and studioUrl sets 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, and recoverResume() 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 updateState to 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's stateSchema, and leaves keys it wasn't given alone, including changes parallel steps made. A key set to undefined is removed. (#29370)

    setState keeps 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)

    backgroundProcesses callbacks on execute_command now receive, when available, the agentId, threadId, resourceId, and runId of the call that started the process, so hosts can route exit notices to the right conversation. onExit also receives killedByAbort, which is true when 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}`);
      },
    },

    truncateOutput and DEFAULT_TAIL_LINES are now exported from @mastra/core/workspace, so hosts can trim process output the same way execute_command does.

  • Added getRunOwnerships({ runIds }) to workflows storage (#28712). It returns the ownership records of many runs at once, in a Map keyed by run ID; runs without a stored record are left out. Stores without a batch query fall back to reading each run with getRunOwnership(), 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: true in listWorkflowRuns(): each run's snapshot comes back as only status, timestamp and, 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() and updateWorkflowRunHeader() now move a run's updatedAt, 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 own setState changes. Pass top-level keys to get only those keys. (#29370)

    Reading state in a run stored with the experimental storageVersion: 2 option now throws, on both the default and evented engines. Use getState() 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 storageVersion option to createDurableAgent and createEventedAgent. Set it to 2 to 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 stays 1, and runs stored before you change the option keep their version.

Patch Changes

  • Fixed retries in dountil and dowhile loops 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 an id. (#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 fetchWithRetry now 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-utils 4.0.66 and 5.0.81, @ai-sdk/provider 4.0.38). (#30518)

  • Fixed Gateway v2 deployments showing models they cannot use. (#29445)

  • Fixed resumed step retries and perStep runs 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 ProcessorStepOutputSchema dropping providerMetadata in the outputStep phase. (#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 foreach iterations 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 after restart() read it but before restart() 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's defaultOptions onFinish, onError and onAbort callbacks. (#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_command now 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 shouldPersistSnapshot skips running snapshots, when replaying from a step that comes before a failed foreach step. (#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 experimental storageVersion: 2 option 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_UNVERIFIED when 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 output array. (#29370)

  • processToolResult now sees and can rewrite a tool's toModelOutput result. (#30401)

  • Fixed background tasks with timeoutMs: 0 being 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 onStepFinish takes 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 showed stop for every call, and now shows the real reason, such as tool-calls or length. 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-base and @opentelemetry/core ^2.12.1, OTLP exporters ^0.223.1) so they no longer resolve to releases that pin @opentelemetry/resources 2.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 listScores in 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_messages and search_memory from the built-in MCP memory toolset, and added a read-only get_working_memory tool. (#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: true now returns only each run's status, timestamp and, 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 mastracode crashing 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-sdk now ships its own copy of the Knowledge scope id encoder instead of importing encodeKnowledgeScopeId from @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_user questions 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.onPluginError now 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 reloadError instead 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-1 to gpt-image-2.5-sunburst. (#30364)

  • The resourceId callback on userConnectRoutes() now receives the authenticated user as a typed MastraUser, the same user that agent callbacks such as tools receive. (#30340)

  • Fixed posthog_run_query failing provider-response validation whenever PostHog returned column types, which it does for every query with columns, even select 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: true now returns only each run's status, timestamp and, 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/sdk to @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)

    E2BSandbox takes a user option. Every command the agent runs — executeCommand and background processes alike — runs as that user instead of the template's default user, which has to keep sudo because mounting needs it. Without the option, nothing changes.

    S3Filesystem and GCSFilesystem take an owner option, { 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 user must 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_snapshots and intake_label_routes tables are no longer created, and the background file-listing capture that filled filesystem_snapshots no longer runs.
    • The waitForPendingFilesystemCapture export is removed. Remove any call to it; there is nothing left to wait for.
    • Project repository responses no longer include sandboxWorkdir or lastBuiltAt, and linking a repository no longer accepts sandboxWorkdir.

    Upgrading

    Update @mastra/pg or @mastra/libsql together with @mastra/factory. Older adapter versions keep the retired columns required on existing databases, which makes card, rule and repository writes fail.

  • 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 as factory.skill.created and factory.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.opened event, and the default rule Trusted pull requests take a waiting issue to Review moves 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 a rule_retired entry in the intake decision log naming it, since the default rule may not cover what it did. New join routes are refused with 422 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 moveToBoardKey to 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.trusted replaces author.trusted (rules saved with the old name still work), and the new pullRequest.trusted tests the event's pull request author, or the author of the card's working pull request.

    { "field": "pullRequest.trusted", "operator": "equals", "value": true }

    Breaking: newestOpenPullRequestNumber is no longer exported from @mastra/factory/boards. Use workingPullRequest(item) with pullRequestSourceNumber to 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 like sandbox,intake). FACTORY_METRICS_INTERVAL_MS (default 60s, minimum 15s) and FACTORY_METRICS_MAX_PER_MIN (default 500) tune how often records are sent and cap their volume. Metrics are named mastra_factory_* and labeled with service (api, worker or all) 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 intake option or FACTORY_INTAKE_EVALUATOR (intake-order or route-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-order runs 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-order sets the order, the project's evaluator, or both; GET reports the evaluator in use and where it came from (evaluatorSource).
    • GET /web/factory/projects/:id/intake/not-routed lists items no board took, oldest first, a page at a time (limit, cursor); POST .../intake/not-routed/:decisionId/route-again files 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 (the factory_create_work_item tool now accepts a board for this), and moving a rule to another board is refused with intake_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 (or MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT); 0 keeps 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-queue adds a lane to each run, queuedByLane, and slots.interactive, and lists waiting replies before automated runs. A run's position now counts within its lane, so a waiting reply and the oldest automated run are both 1. The other fields keep their meaning; slots.inUse counts automated slots, including any a reply borrowed.

    GitHub rule actors now carry human: true when 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 (user by default, or org). Saving with previousId edits 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 the MASTRACODE_DISPATCH_MAX_IN_FLIGHT environment 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 of Starting 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 from GET /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 security with 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/phases returns, 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-options returns 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 a version of 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.evaluator option from MastraFactory. New projects already use the intake order, so the option only mattered for older projects. (#30676)

    • MastraFactory no longer accepts intake: { evaluator }, and throws at startup when it is passed.
    • GET /web/factory/projects/:id/intake-order no longer reports evaluatorSource: 'option'; it reports env, project, or legacy.

    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 read evaluatorSource: 'option' should treat env as the forced case.

  • Factory takes an optional coAuthor for 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-run runs 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 unsaved boards rules or an unsaved order to preview an edit: the response also says how many items would land somewhere else.

    Tester

    POST /web/factory/projects/:id/intake/test takes one item, by url or by the itemId of 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 with not_linked.

    On a card, the tester also replays its recent status events, and one event passed 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 pass false to keep every session loaded:

    const factory = new MastraFactory({
      storage,
      idleSessionUnload: { idleMs: 60 * 60_000, sweepIntervalMs: 5 * 60_000 },
    });
  • Removed the unused sandboxProvider field 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 with custom or none. (#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_provider column. Existing factories keep the column and its stored values, and Factory simply stops writing it.

    Upgrading

    Stop passing sandboxProvider when linking a project repository:

    // Before
    await github.projectRepositories.link({ orgId, connectionId, repositoryId, sandboxProvider: 'local' });
    
    // After
    await github.projectRepositories.link({ orgId, connectionId, repositoryId });

    Update mastra together with @mastra/factory. The Factory UI ships with mastra, and repository linking fails when one of the two is older than the other.

  • 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_item takes rerun: true to 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. Without rerun, 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's url.
    • 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 as ENG-42. With several repositories linked, the link finds the right card where a bare #12 might not. factory_list_work_items takes the same references as its query.
    • factory_inspect_work_item lists the card's stage, whether it can run again, and the stages its board lets it move to next.
    • factory_start_session only starts side sessions. Its workItem and role inputs 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/config with { "dependabot": { "enabled": true, "sourceIds": ["owner/repo"] } }. Open alerts in those repositories become cards labeled security with 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-rows returns 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-activity returns which sessions are running, waiting on a person or still coming up. Both answer 304 when 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 carries candidates), and factory_list_attention no longer returns needsRepository or linkedRepositories.

  • 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 is pull_request.*. A route on work_item.opened files new issues, and a route on pull_request.opened files new pull requests with no card (and moves an issue's card when its pull request opens). work_item.created keeps its meaning: it files new issues and new pull requests alike, so existing routes, and routes created without on, behave as before. New projects get their pull request routes on pull_request.opened. A pull_request.opened route stored by an earlier version still only moves cards, through every edit (the API marks it pullRequestOpenedMovesOnly: true); add a route to file pull requests.

    New events — work_item.updated fires when an issue's labels or assignees change, and pull_request.updated when a pull request's do, on its own card or an issue card it is attached to; pull_request.reopened moves 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.hasPullRequest and item.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 view or 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 tools option, 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 scorers to 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-run and mastra api factory intake test to 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 dev startup 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 git and gh. (#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_branch now reports what it pushed. (#30700)

  • Approving a held Factory run with factory_resolve_proposal, or retrying a failed one with factory_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

  • GoogleCloudPubSub now reports redeliversUnacked as true: 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 failed in 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-spec parts, and the reply's text keeps only the prose. Render them with useJsonRenderMessage() 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_STATE request 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.

@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 with The 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: 2 option can now be written by several workers at once, as evented workflows and createEventedAgent do. Concurrent foreach iterations 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/pg 1.36.0-alpha.0 or @mastra/libsql 1.30.0-alpha.0, the store adds the columns this needs to the mastra_workflow_runs table on startup, and those runs keep working.

    Also in: @mastra/pg@1.37.0

Patch Changes

  • Fixed thread state writes failing with SQLITE_BUSY while 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: true now also returns parentWorkflow: { workflowId, runId } for nested runs, next to status and timestamp (#28712). (#30274)

    Also in: @mastra/pg@1.37.0

@mastra/mcp@2.10.0

Minor Changes

  • Added appsRequireClientSupport to MCPServer. 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 (no ui:// 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 at initialize gets an Mcp-Session-Id that 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 transform functions now also receive apps in their context: true when the calling client renders MCP Apps, so a transform can send a short summary to the model and the full data to the app as structuredContent.

  • MCPServer accepts a maxRequestBodySize option, so HTTP requests larger than the 4 MiB default are no longer answered with a 413 before 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 a 413 JSON-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 to startHTTP requests only; stdio has 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 the analyze_metrics call 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 },
    });

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' on MastraStorageExporter in 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-exporter changelog for the attribute changes. (#30342)

Patch Changes

  • Fixed Mastra logs being dropped by OtelBridge in 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 exporter declare 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 use gen_ai.usage.reasoning_tokens.
    • gen_ai.tool.definitions is now a list of { type, name } objects instead of a list of tool names.
    • gen_ai.system_instructions is now a list of text parts, such as [{"type":"text","content":"..."}], instead of plain text.
    • Each message in gen_ai.output.messages now has a finish_reason. The reason is unknown when the model did not report one.
    • gen_ai.request.stop_sequences and gen_ai.response.finish_reasons are now lists instead of JSON text.
    • Agent run spans now include gen_ai.provider.name, and workflow run spans now include gen_ai.workflow.name.
    • gen_ai.provider.name now uses the OpenTelemetry provider names for AI SDK provider ids, such as openai for openai.chat and gcp.vertex_ai for google.vertex.chat.
    • If you create a SpanConverter yourself, pass format: 'GenAI_v1_41_0'. The old 'GenAI_v1_38_0' value no longer type-checks.

@mastra/pg@1.37.0

Patch Changes

  • Fixed PgVector calls failing with "Vector table ... does not exist" after an index was deleted with deleteIndex() and created again while that PgVector instance 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 with POST /v1/browsers/sessions on the Platform and connects to the returned CDP URL; pass cdpUrl to connect to a session you already provisioned, with no token or API call. The access token falls back to MASTRA_PLATFORM_ACCESS_TOKEN / MASTRA_PLATFORM_SECRET_KEY, the project to MASTRA_PROJECT_ID, and the API URL to MASTRA_BROWSER_API_URL. @mastra/platform now depends on @mastra/stagehand at 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. PlatformMemory is a drop-in memory for Agent that loads observations and recent messages from a Platform Memory instance and saves each turn back; observation and reflection run on the Platform. PlatformMemoryClient exposes the same API directly. Credentials fall back to MASTRA_PLATFORM_ACCESS_TOKEN / MASTRA_PLATFORM_SECRET_KEY. PlatformMemory uses MASTRA_MEMORY_INSTANCE_ID; PlatformKnowledge uses MASTRA_KNOWLEDGE_INSTANCE_ID. PlatformKnowledge takes every scope declaration and access rule from its instance, Memory's and Platform importers' included, and has no scopes option. Agents read imported pages when their runs hold the scope an importer's rule grants (for now imports:all). (#29428)

    import { PlatformMemory, PlatformKnowledge, PlatformSandbox, PlatformFilesystem } from '@mastra/platform';
    
    const agent = new Agent({ name: 'assistant', model, memory: new PlatformMemory() });

Patch Changes

  • PlatformKnowledge now supports listing pins: knowledge_pin with kind: 'list' pins a page's listing on hosted Knowledge instead of refusing it as an old storage adapter. (#29428)

  • PlatformMemory fixes for read-only runs and working memory: (#29428)

@mastra/platform-workspace@1.13.1

Patch Changes

  • Fixed commands with a cwd that 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 (xs 14px, sm 16px, md 18px, lg 22px) 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: the xs and inline avatars 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 in central-icons.json and 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_WIDTHS exports them; pass minWidth only 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.Meter keeps one layout in both states. It accepts loading, which shows the card at its loaded size, and railValue, 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=" " />
  • 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 unavailableReason to ModelPicker. 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."
    />
  • LogDataPanel accepts an actions prop 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.

  • InputGroupAddon now insets its icon like a Button does (the group's --control-px and --control-gap), so a leading or trailing icon in any field lines up with the icons of the controls beside it. A field built from InputGroup parts by hand gets the same inset as SearchInput. An icon InputGroupButton is now a chip inset in the field (8px shorter than it, with an even ring around it) instead of a full-height circle. (#30062)

    SearchInput is now plain InputGroup composition (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 over ListSearch'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 accept debounceMs, which delays onValueChange while typing; clearing reports right away. shortcut turns on the Cmd/Ctrl+Shift+F focus shortcut, and listSearchProps bundles a list page's size, debounceMs and shortcut. ListSearch and SearchFieldBlock are 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's onSearch → onValueChange, value → defaultValue, shortcutDisabled → leave out shortcut. It defaulted to size="sm" and a 300ms debounce; pass them. To reset a field that keeps its own text, remount it with a key.
    • SearchFieldBlock → SearchInput, inside a Field when it needs a visible label.
    • SearchInput's label is now the input's aria-label instead 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, timeseriesSeriesSchema and scoresOptionsSchema, with their types.
    • Value expression schemas and types: valueExprSchema, valueRefSchema, queryRefSchema, ValueExpr, ValueRef and LabelledValue.
    • The allowed formats, colors and KPI icons: VALUE_FORMATS, formatSchema, CHART_COLOR_NAMES, SERIES_COLORS, colorSchema, KPI_ICONS, and the ValueFormat, ChartColorName and KpiIcon types.
    import { kpisOptionsSchema, valueExprSchema } from '@mastra/playground-ui/domains/dashboards';
    
    kpisOptionsSchema.parse({ items: [{ label: 'Runs', format: 'count', value: { query: 'runs' } }] });
  • 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.

    AppShell slides its content automatically. A Sidebar rendered outside AppShell has no page to slide, so either move the page into AppShell or 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-ui components 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 inside Icon like any other icon. The icons are licensed under the Central Icons license, not Apache-2.0. See CENTRAL-ICONS-LICENSE.md in 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 a Card or a dialog. The panel pads each row and draws a divider between them, so plain elements and SettingsRows both work as rows. (#30699)

    <DialogBody>
      <CardInset>
        <div>Source</div>
        <div>Schedule</div>
      </CardInset>
    </DialogBody>

    Removed SectionCard and CardHeading. 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)

  • CodeDiff with a file header now shows its lines flush against the header and the card's bottom edge, so stacked diffs in a CodeDiffList read 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-parent lint 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)

  • CodeDiff now 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.NavShowMore accepts a ref to 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-alerts and no-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() and streamKey() to RedisStreamsPubSub, 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

  • RedisStreamsPubSub now reports redeliversUnacked as true while its reclaim loop runs (reclaimIntervalMs above 0). (#30279)

  • Fixed workflow runs that stayed running on 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.definitions is now a list of { type, name } objects instead of a list of tool names. gen_ai.provider.name now uses the OpenTelemetry provider names, such as openai for openai.chat. Each message in gen_ai.output.messages now has a finish_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_trace opens Studio's trace viewer: the timeline, with each span's details on click.
    • query_traces, list_traces, list_logs, and analyze_metrics open 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-components to 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.mcp options: apps: false turns the apps off, and studioUrl sets where the apps' Open in Studio button points. Under mastra dev, studioUrl defaults 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/core peer dependency floor to 1.84.0 to match the @mastra/libsql version it depends on. (#29370)

@mastra/valkey-streams@0.6.3

Patch Changes

  • Fixed workflow runs that stayed running on Valkey Streams when a worker shut down while one of their steps was still running. (#30387)

  • ValkeyStreamsPubSub now reports redeliversUnacked as true while its reclaim loop runs (reclaimIntervalMs above 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

Don't miss a new mastra release

NewReleases is sending notifications on new releases.