Durable agents now use the wrapped Agent's stream bus instead of
constructing a second one. An Agent-level pubsub carries both run frames
and thread events, including after registration and forks; evented
execution still uses Mastra's shared transport. Standalone durable
agents remain observable, and plain-run records and abort checks stay
separate from durable execution.
Previously, observing across replicas required repeating the pubsub on
the durable wrapper. This now works with the Agent configuration alone:
```ts
const agent = createDurableAgent({
agent: new Agent({ id: 'assistant', name: 'Assistant', instructions, model, pubsub }),
});
```
Inngest explicitly exposes its detached-streaming capability without
migrating its bus. The server retains the `isDurableAgentLike` fallback
in `hasResumableStreams` for compatibility with older Inngest wrappers:
their proxy can inherit `false` from a plain Agent or lack the method
entirely. Server and Inngest versions are not coupled, so removing the
fallback would silently turn HTTP disconnects into run cancellation on
supported mixed-version installs. This is a deliberate, user-approved
exception to the ticket's shortcut-removal bullet; no peer-dependency
bump is needed while the fallback remains. Regression coverage exercises
capability `true`, `false`, and missing; the latter two fail without the
fallback.
Server branch audit (`packages/server/src/server/handlers/agents.ts`):
`validateDurableToolCallAccess` (line 298) remains because approvals
need durable workflow snapshots; `authorizeRunAccess` (2676) remains
because durable ownership uses workflow rows/local and replay owners
rather than plain run records (COR-1542). The two abort-route branches
(2724 and 2742) retain durable cancellation support and its
missing/finished-run acknowledgement semantics, not separate transports.
The observe-route branch (3141) remains for generation-fenced
`__subscribeToRunStream` and the Inngest adapter's `pubsub` fallback;
consolidating observation is COR-1541, and migrating Inngest's bus is
COR-1539. The recover-route guard (3746) remains because only durable
execution has recoverable workflow snapshots. None of these remaining
branches requires a second stream bus on core DurableAgent.
The Mastra-fallback regression also runs through a fork created after
registration, both with and without resolving the bus before
registration. Another replica must receive replay plus live tail through
finish, and the terminal frame must be published on Mastra's transport.
The latest targeted rerun passed 33 tests, including cache-policy
warnings and plain-publisher isolation across both durable storage
variants; core typecheck, targeted lint, formatting and diff checks
passed.
Verified with 1,643 core durable/stream tests, 78 AIMock parity tests,
292 server handler tests (including the mixed-version capability cases),
119 Inngest tests, and six real Redis cross-server cases covering live
observation, thread events and HTTP Stop. Typechecks, lint and
formatting pass. The Agent-pubsub regression failed before the fix; a
built-package red/green demo also confirms the transport change. An
earlier approval-resume timing failure passed in isolation and on the
final full rerun.
Fixes COR-1540
## Transport precedence and upgrade scope
Default-engine durable run transport precedence is now: explicit
`createDurableAgent` pubsub → wrapped Agent pubsub → Mastra pubsub.
Evented runs retain Mastra's shared transport. Mastra-only
configurations are unchanged.
If the wrapped Agent already specifies a different transport from Mastra
and the wrapper has no override, this fix changes the effective
run-frame and remote Stop transport. To preserve routing across an
upgrade, explicitly pass the previous transport to `createDurableAgent`
or align the Agent and Mastra transports. The wrapper configures the
shared stream bus, so its override also affects resumable streams from
direct calls on the wrapped Agent. The core changeset includes this
upgrade note.
A local investigation used separately built pre-change main
(`
|
History
|
|
|---|---|---|
| .. | ||
| __recordings__ | ||
| scripts | ||
| src | ||
| tools | ||
| .gitignore | ||
| AGENTS.md | ||
| api-extractor.json | ||
| CHANGELOG.md | ||
| docker-compose.yaml | ||
| lint-staged.config.js | ||
| oxlint.config.ts | ||
| package.json | ||
| README.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| tsdown.config.ts | ||
| turbo.json | ||
| vitest.config.ts | ||
| vitest.isolated-tests.ts | ||
| vitest.no-isolate-setup.ts | ||
@mastra/core
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
It includes everything you need to go from early prototypes to production-ready applications. Mastra integrates with frontend and backend frameworks like React, Next.js, and Node, or you can deploy it anywhere as a standalone server. It's the easiest way to build, tune, and scale reliable AI products.
Installation
@mastra/core is an essential building block for a Mastra application. We recommend following the installation guide to get started with Mastra.
You can install the package like so:
npm install @mastra/core
Core Components
-
Mastra (
/mastra): Central orchestration class that initializes and coordinates all Mastra components. Provides dependency injection for agents, workflows, tools, memory, storage, and other services through a unified configuration interface. Learn more about Mastra -
Agents (
/agent): Autonomous AI entities that understand instructions, use tools, and complete tasks. Encapsulate LLM interactions with conversation history, tool execution, memory integration, and behavioral guidelines. Learn more about Agents -
Workflows (
/workflows): Graph-based execution engine for chaining, branching, and parallelizing LLM calls. Orchestrates complex AI tasks with state management, error recovery, and conditional logic. Learn more about Workflows -
Tools (
/tools): Functions that agents can invoke to interact with external systems. Each tool has a schema and description enabling AI to understand and use them effectively. Supports custom tools, toolsets, and runtime context. Learn more about Tools -
Memory (
/memory): Thread-based conversation persistence with semantic recall and working memory capabilities. Stores conversation history, retrieves contextually relevant information, and maintains agent state across interactions. Learn more about Memory -
MCP (
/mcp): Model Context Protocol integration enabling external tool sources. Supports SSE, HTTP, and Hono-based MCP servers with automatic tool conversion and registration. Learn more about MCP -
Observability: Type-safe observability system tracking AI operations through spans. Provides flexible tracing with event-driven exports, configurable sampling, and pluggable processors and exporters for real-time monitoring. Full observability features are available in the
@mastra/observabilitypackage. Learn more about Observability -
Storage (
/storage): Pluggable storage layer with standardized interfaces for multiple backends. Supports PostgreSQL, LibSQL, MongoDB, and other databases for persisting agent data, memory, and workflow state. Learn more about Storage -
Vector (
/vector): Vector operations and embedding management for semantic search. Provides unified interface for vector stores with filtering capabilities and similarity search. Learn more about Vector -
Server (
/server): HTTP server implementation built on Hono with OpenAPI support. Provides custom API routes, middleware, authentication, and runtime context for deploying Mastra as a standalone service. Learn more about Server -
Voice (
/voice): Voice interaction capabilities with text-to-speech and speech-to-text integration. Supports multiple voice providers and real-time voice communication for agents. Learn more about Voice -
Browser (
/browser): Base classes and utilities for browser automation. Provides theMastraBrowserabstract class, thread management, and screencast streaming for building browser providers. Use with@mastra/agent-browseror@mastra/stagehandfor complete browser automation. Learn more about Browser
License
This package uses a dual-license model:
- Apache License 2.0: The vast majority of this codebase is open source under Apache-2.0.
- Mastra Enterprise License: Code in any directory named
ee/(e.g.,@mastra/core/auth/ee) is source-available under the Mastra Enterprise License. These features require a valid enterprise license for production use but can be freely used for development and testing.
See LICENSE.md for the full license mapping and ee/LICENSE for the enterprise license terms.