This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
> The changelog information of each package has been omitted from this
message, as the content exceeds the size limit.
## @mastra/auth-auth0@1.3.0-alpha.0
## @mastra/auth-clerk@1.4.0-alpha.0
## @mastra/auth-okta@0.3.0-alpha.0
## @mastra/auth-supabase@1.2.0-alpha.0
## @mastra/client-js@1.60.0-alpha.13
## @mastra/auth@1.2.0-alpha.0
## @mastra/core@1.83.0-alpha.13
## @mastra/playground-ui@69.0.0-alpha.15
## @mastra/rag@2.8.0-alpha.3
## @mastra/server@1.83.0-alpha.13
## @mastra/server-adapters-test-suite@0.3.0-alpha.5
## @mastra/auth-better-auth@1.1.11-alpha.2
## @mastra/auth-cloud@1.2.9-alpha.0
## @mastra/auth-neon@0.3.6-alpha.1
## @mastra/auth-workos@1.6.9-alpha.0
## @mastra/discord@1.3.4-alpha.0
## @mastra/react@1.15.0-alpha.13
## @mastra/deployer-cloud@1.83.0-alpha.13
## @mastra/deployer-cloudflare@1.2.42-alpha.3
## @mastra/deployer-netlify@1.2.42-alpha.1
## @mastra/deployer-sandbox@0.3.27-alpha.1
## @mastra/deployer-vercel@1.2.42-alpha.1
## @mastra/longmemeval@1.1.42-alpha.13
## @mastra/opencode@0.1.42-alpha.13
## @mastra/factory@0.28.0-alpha.15
## create-factory@0.4.3-alpha.15
## @mastra/code-sdk@1.19.0-alpha.15
## mastracode@0.50.0-alpha.14
## @mastra/agent-builder@1.2.1-alpha.5
## mastra@1.39.0-alpha.15
## @mastra/connect@1.4.0-alpha.6
## @mastra/deployer@1.83.0-alpha.13
## @mastra/editor@0.17.1-alpha.7
## @mastra/mcp@2.9.0-alpha.5
## @mastra/mcp-docs-server@1.3.13-alpha.17
## @mastra/memory@1.41.1-alpha.5
## @mastra/schema-compat@1.4.0-alpha.2
## @mastra/elysia@0.1.23-alpha.13
## @mastra/express@1.5.27-alpha.13
## @mastra/fastify@1.5.27-alpha.13
## @mastra/hono@1.7.25-alpha.13
## @mastra/koa@1.7.27-alpha.13
## @mastra/nestjs@0.3.0-alpha.13
## @mastra/next@0.2.41-alpha.13
## @mastra/tanstack-start@0.2.41-alpha.13
## @mastra/voice-google-gemini-live@0.14.19-alpha.2
## @mastra/voice-openai-realtime@0.14.9-alpha.3
## @mastra/voice-xai-realtime@0.2.18-alpha.2
## @mastra/inngest@1.11.2-alpha.9
## @mastra/temporal@0.6.0-alpha.13
## create-mastra@1.39.0-alpha.15
## @internal/playground@1.39.0-alpha.15
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Dynamic agent config callbacks now get the authenticated end user as an
optional `user` argument, so you can personalize an agent without
digging auth keys out of `requestContext` yourself. It works in any
`DynamicArgument` callback: instructions, model, tools, memory,
workspace, processors, scorers, and so on.
```ts
import { Agent } from '@mastra/core/agent';
const supportAgent = new Agent({
id: 'support-agent',
instructions: ({ user }) =>
user ? `You are helping ${user.name ?? user.id}.` : 'You are a helpful assistant.',
model: ({ user }) => (user?.role === 'admin' ? 'openai/gpt-5' : 'openai/gpt-5-mini'),
tools: ({ user }) => (user ? { accountTool, ...(user.role === 'admin' ? { adminTool } : {}) } : {}),
memory: ({ user }) => (user ? userMemory : undefined),
});
```
`user` always has the same `MastraUser` shape, no matter which auth
provider you use, and it's `undefined` for unauthenticated requests:
```ts
import type { MastraUser } from '@mastra/core/types';
// { id: string; name?: string; email?: string; avatarUrl?: string; role?: string }
```
The server auth middleware builds it through a new overridable
`toMastraUser()` on `MastraAuthProvider`. The default handles common
shapes (`id`/`sub`/`userId`, `name`, `email`, `avatarUrl`/`picture`,
`role`), and JWT, Cloud, Supabase, Neon and Better Auth ship overrides
for their user objects. Custom providers can map their own shape:
```ts
import { MastraAuthProvider } from '@mastra/core/server';
import type { MastraUser } from '@mastra/core/types';
class MyAuth extends MastraAuthProvider<MyUser> {
async authenticateToken(token: string) { /* ... */ }
async authorizeUser(user: MyUser) { return true; }
toMastraUser(user: MyUser): MastraUser {
return { id: user.accountId, name: user.profile.displayName, role: user.permissions.primaryRole };
}
}
```
Inline auth configs can pass `toMastraUser` too. If the provider user
has no role and an RBAC provider is configured, the primary RBAC role
fills it in, so `user.role` also works with WorkOS, Okta, Google and
Neon. The raw provider user is still available when you need
provider-specific fields, and the new context key is reserved, so
clients can't spoof it through the request body:
```ts
instructions: ({ requestContext }) => {
const rawUser = requestContext.get('mastra__user'); // provider-specific object, unchanged
// ...
},
```
Dynamic `vectorStore` resolvers on RAG tools get `user` as well:
```ts
createVectorQueryTool({
indexName: 'docs',
model: embedder,
vectorStore: ({ user }) => (user ? tenantStores.get(user.id)! : sharedStore),
});
```
Inside core, every place that invoked a `DynamicArgument` callback
inline now goes through a single `resolveDynamicArgument` helper, which
reads the user from `requestContext` at call time. This is non-breaking:
callbacks get an extra optional field, providers get a method with a
working default. Requests served through an `MCPServer` don't get `user`
yet, since MCP builds its own request context; that's documented.
Tested with unit tests for the helper, normalization and each provider
override, middleware tests (inline config, provider role, RBAC role,
CompositeAuth ordering, unauthenticated), regression tests for the
migrated call sites, and an end-to-end test where an agent behind a fake
auth provider gets personalized instructions. Core, server, rag and the
touched auth packages typecheck clean, and their suites pass.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
When a signed-in user makes a request, configuration callbacks can now
use a standard set of details about that user. When a workflow resumes,
it uses the new request’s user details instead of restoring them from
the earlier run.
## Summary
- Added optional `user` data to `DynamicArgument` callbacks and RAG
vector-store resolvers. Callbacks can also use `getRequestUser()` to
read the normalized user from request context.
- Added the `MastraUser` type and `toMastraUser()` normalization hooks
for auth providers and inline auth configs. The server stores the
normalized user in a reserved request-context key and uses the primary
RBAC role when the user has no role.
- Updated core dynamic configuration paths to use the shared resolver.
Added user support to agent scopes and migrated A2A memory resolution.
- Added `withoutLiveRequestKeys()` to remove live authentication and
authorization data from saved context during workflow resume, restart,
and time travel. Saved non-authentication context, such as tenant data,
remains available.
- Added documentation and changesets. Raised relevant `@mastra/core`
peer dependency minimums to 1.81.0. MCPServer requests do not receive
the normalized `user`.
## Validation
The author reports passing typechecks and test suites across core,
server, RAG, and several auth packages. The author also reports three
failing Inngest tests and earlier failures in evented workflow and
scheduler tests, which reportedly fail the same way on comparison
sources. These results are author-reported and have not been
independently verified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
> The changelog information of each package has been omitted from this
message, as the content exceeds the size limit.
## @mastra/client-js@1.60.0-alpha.0
## @mastra/react@1.15.0-alpha.0
## @mastra/factory@0.28.0-alpha.0
## @mastra/code-sdk@1.19.0-alpha.0
## mastra@1.39.0-alpha.0
## @mastra/core@1.83.0-alpha.0
## @mastra/mcp@2.9.0-alpha.0
## @mastra/mcp-apps-components@0.1.0-alpha.0
## @mastra/playground-ui@69.0.0-alpha.0
## @mastra/server@1.83.0-alpha.0
## @mastra/nestjs@0.3.0-alpha.0
## @mastra/clickhouse@1.30.0-alpha.0
## @mastra/duckdb@1.19.0-alpha.0
## @mastra/libsql@1.30.0-alpha.0
## @mastra/pg@1.36.0-alpha.0
## @mastra/temporal@0.6.0-alpha.0
## @mastra/auth-better-auth@1.1.11-alpha.0
## @mastra/deployer-cloud@1.83.0-alpha.0
## @mastra/deployer-cloudflare@1.2.42-alpha.0
## @mastra/deployer-netlify@1.2.42-alpha.0
## @mastra/deployer-sandbox@0.3.27-alpha.0
## @mastra/deployer-vercel@1.2.42-alpha.0
## @mastra/longmemeval@1.1.42-alpha.0
## @mastra/opencode@0.1.42-alpha.0
## create-factory@0.4.3-alpha.0
## mastracode@0.49.1-alpha.0
## @mastra/arize@1.3.30-alpha.0
## @mastra/arthur@0.4.30-alpha.0
## @mastra/braintrust@1.3.27-alpha.0
## @mastra/datadog@1.4.22-alpha.0
## @mastra/deepeval@0.1.24-alpha.0
## @mastra/laminar@1.3.32-alpha.0
## @mastra/langfuse@1.6.6-alpha.0
## @mastra/langsmith@1.4.3-alpha.0
## @mastra/observability@1.23.2-alpha.0
## @mastra/otel-bridge@1.5.22-alpha.0
## @mastra/otel-exporter@1.5.2-alpha.0
## @mastra/posthog@1.4.7-alpha.0
## @mastra/sentry@1.2.32-alpha.0
## @mastra/agent-builder@1.2.1-alpha.0
## @mastra/connect@1.3.2-alpha.0
## create-mastra@1.39.0-alpha.0
## @mastra/deployer@1.83.0-alpha.0
## @mastra/editor@0.17.1-alpha.0
## @mastra/mcp-docs-server@1.3.13-alpha.0
## @mastra/memory@1.41.1-alpha.0
## @mastra/rag@2.7.3-alpha.0
## @mastra/redis-streams@0.8.1-alpha.0
## @mastra/elysia@0.1.23-alpha.0
## @mastra/express@1.5.27-alpha.0
## @mastra/fastify@1.5.27-alpha.0
## @mastra/hono@1.7.25-alpha.0
## @mastra/koa@1.7.27-alpha.0
## @mastra/next@0.2.41-alpha.0
## @mastra/tanstack-start@0.2.41-alpha.0
## @mastra/spanner@1.11.2-alpha.0
## @mastra/turso@0.1.21-alpha.0
## @mastra/inngest@1.11.2-alpha.0
## @mastra/gcs@0.3.6-alpha.0
## @internal/playground@1.39.0-alpha.0
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
> The changelog information of each package has been omitted from this
message, as the content exceeds the size limit.
## @mastra/client-js@1.59.0-alpha.2
## @mastra/factory@0.27.0-alpha.2
## @mastra/code-sdk@1.18.0-alpha.2
## mastra@1.38.0-alpha.2
## @mastra/core@1.82.0-alpha.2
## @mastra/editor@0.17.0-alpha.2
## @mastra/server@1.82.0-alpha.2
## @mastra/clickhouse@1.29.0-alpha.1
## @mastra/duckdb@1.18.0-alpha.1
## @mastra/pg@1.35.0-alpha.2
## @mastra/platform-workspace@1.12.0-alpha.1
## @mastra/react@1.14.1-alpha.2
## @mastra/deployer-cloud@1.82.0-alpha.2
## @mastra/deployer-sandbox@0.3.26-alpha.1
## @mastra/longmemeval@1.1.41-alpha.2
## @mastra/opencode@0.1.41-alpha.2
## @mastra/parallel@0.1.5-alpha.0
## create-factory@0.4.2-alpha.2
## mastracode@0.49.0-alpha.2
## @mastra/arize@1.3.29-alpha.1
## @mastra/arthur@0.4.29-alpha.1
## @mastra/braintrust@1.3.26-alpha.1
## @mastra/datadog@1.4.21-alpha.1
## @mastra/deepeval@0.1.23-alpha.1
## @mastra/laminar@1.3.31-alpha.1
## @mastra/langfuse@1.6.5-alpha.1
## @mastra/langsmith@1.4.2-alpha.1
## @mastra/observability@1.23.1-alpha.1
## @mastra/otel-bridge@1.5.21-alpha.1
## @mastra/otel-exporter@1.5.1-alpha.1
## @mastra/posthog@1.4.6-alpha.1
## @mastra/sentry@1.2.31-alpha.2
## @mastra/agent-builder@1.1.33-alpha.2
## @mastra/deployer@1.82.0-alpha.2
## @mastra/mcp@2.8.0-alpha.1
## @mastra/mcp-docs-server@1.3.12-alpha.3
## @mastra/memory@1.41.0-alpha.2
## @mastra/playground-ui@68.0.0-alpha.2
## @mastra/rag@2.7.2-alpha.0
## @mastra/elysia@0.1.22-alpha.2
## @mastra/express@1.5.26-alpha.2
## @mastra/fastify@1.5.26-alpha.2
## @mastra/hono@1.7.24-alpha.2
## @mastra/koa@1.7.26-alpha.2
## @mastra/nestjs@0.2.41-alpha.2
## @mastra/next@0.2.40-alpha.2
## @mastra/tanstack-start@0.2.40-alpha.2
## @mastra/dsql@1.5.6-alpha.0
## @mastra/libsql@1.29.0-alpha.1
## @mastra/mongodb@1.26.0-alpha.1
## @mastra/mssql@1.11.1-alpha.0
## @mastra/mysql@0.16.0-alpha.2
## @mastra/oracledb@0.5.6-alpha.0
## @mastra/spanner@1.11.1-alpha.0
## @mastra/turso@0.1.20-alpha.1
## @mastra/voice-google@0.14.5-alpha.0
## @mastra/inngest@1.11.1-alpha.1
## @mastra/temporal@0.5.0-alpha.2
## @mastra/e2b@0.16.1-alpha.1
## create-mastra@1.38.0-alpha.2
## @internal/playground@1.38.0-alpha.2
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
`PlatformSandbox` now implements the standard `networking` capability.
`sandbox.networking.getPortUrl(port)` returns the URL of a port in the
running sandbox:
```typescript
await sandbox.processes.spawn('pnpm dev --host 0.0.0.0 --port 3000')
const url = await sandbox.networking.getPortUrl(3000)
// https://3000-<sandbox id>.sandbox.us.mastra.cloud/
```
Ports are private. Anyone in the sandbox's organization can open the URL
in a browser after signing in to Mastra, and anyone else is turned away.
The URL doesn't expire, so it's the one to share.
It returns `null`, without starting anything, when the sandbox isn't
running or has been destroyed, for an invalid port, or for the sandbox's
control port. Other platform errors are thrown.
## Why
Agents and apps running in a Platform sandbox had no way to hand someone
a link to what they built, like a dev server. Other providers already
expose this through `sandbox.networking`, so code written against that
interface now works with Platform sandboxes too.
Core's `SandboxNetworking` doc comment promised a public URL, so it now
says the URL may ask for sign-in, depending on the provider. With
`publicPorts` (coming separately), Platform URLs open without sign-in
like other providers.
This only covers opening a port in a browser. A server-side caller
without a signed-in browser gets a 401 on a private port. The sandbox
deployer's health check used to count that 401 as a running server. It
now treats a response the preview marks as its own
(`x-mastra-preview-error`) as a provider error, like Vercel's
`x-vercel-error`, so a deploy to a private port fails its health check
instead of reporting success.
## Depends on
mastra-ai/platform#4179 (merged and deployed): the preview proxy marks
its own responses with `x-mastra-preview-error`. The deployer change
relies on it. Verified live: an unsigned request to a preview host on
prod US, prod EU and staging returns `401` with `x-mastra-preview-error:
sign-in-required`.
## Testing
- Deployer: `waitForHealthy` tests against a real local server. An app's
own 200 and 401 count as up. A 410, `x-vercel-error`, and a
preview-marked 401 don't. Without the change, the preview case fails.
- Unit: the address from the platform's preview route, without its
one-time sign-in link. `null` before start, after destroy (410), when
previews aren't served (404), for invalid ports and the control port,
with no request in those cases. Other errors are thrown. Removing the
404/410 handling or returning the sign-in link fails the tests. 331
pass, typecheck clean.
- Live against the platform:
| Check | Result |
| --- | --- |
| `getPortUrl(3000)` before `start()` | `null`, no request |
| `supportsNetworking(sandbox)` | `true` |
| `getPortUrl(3000)` | `https://3000-<id>.sandbox.us.mastra.cloud/` |
| Opening it in a browser without signing in | 302 to the sign-in page |
| Fetching it without signing in | 401 "Sign in to see this preview." |
| `getPortUrl(49983)` | `null` |
| After `destroy()` | `null` |
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Supported Platform sandboxes can now provide a link to an app port.
Health checks also ignore provider sign-in responses, so they do not
mistake them for a healthy app.
## Summary
- Add `PlatformSandbox.networking.getPortUrl(port)` for E2B-backed
sandboxes. The URL is private and requires a signed-in organization
member.
- Return `null` for invalid or reserved ports, a sandbox that is not
running, or a missing or destroyed sandbox. A 404 or 410 from the
preview grant also returns `null`; a 410 clears the matching sandbox ID
and resets its status. Other errors propagate.
- Document port URL access, expiration, and paused-sandbox behavior.
Update Core networking documentation to note that sign-in may be
required, depending on the provider.
- Update `waitForHealthy` to reject provider-edge responses marked by
`x-mastra-preview-error`, alongside HTTP 410 and `x-vercel-error`.
- Add tests for port URL behavior and health-check responses. Test
results were not provided.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
**─────── TLDR ───────**
> Retries, memory, account rotation, the TUI and Factory now read a
failed model call through one reader in `@mastra/core/error`, so one
rule change fixes them all.
Follows #27811, which put this reader in Factory first. Before this PR,
seven hand-written status, code and wording tables disagreed. The retry
processor retried an exhausted quota, because the AI SDK marks every 429
retryable. Rotation only read quota wording on a 400. The run report
said `Bad Request`.
Now `classifyProviderError` reads the HTTP status, the provider codes,
the body and the wording, and every site asks it. Each site keeps only
the signals the reader can't see: a numeric `status`, network errors,
Retry-After and `ProviderAuthRequiredError`.
### Behavior changed
a 429 whose body says the quota is exhausted (`insufficient_quota`)
├─ **was** — retried, and the TUI says to wait a moment
└─ **now** — never retried; the TUI names the quota and
points to billing
a credential or usage failure named only in the provider's body
├─ **was** — no account rotation; Factory reports a plain
run failure
└─ **now** — rotates to the next account; Factory reports
bad credentials
a Factory run report for a failed provider call
├─ **was** — quotes the provider for usage limits only, else
`Bad Request`
└─ **now** — quotes the provider's own reason, cut at 400
characters
a mid-stream provider code, such as a Codex `server_error`, on the web
card
├─ **was** — `Run stopped`, live and after a reload
└─ **now** — named as an outage; the saved part keeps the
codes
a stream error that your own retry matcher and the built-in OpenAI
matcher both accept
├─ **was** — the built-in policy wins: one immediate retry,
no callback
└─ **now** — your matcher's `maxRetries`, `delayMs` and
`onRetry` apply
a tool's `EACCES: permission denied` ending a run
├─ **was** — the reader called it a provider credential
failure
└─ **now** — unknown; only the code form `permission_denied`
reads as auth
### Shape changed
| | | |
|---|---|---|
| **−** | `mastracode/factory/src/provider-error.ts` | its home in
#27811, back in core |
| **−** | memory `context-overflow.ts` | replaced by the reader's
`context_overflow` |
| **−** | `USAGE_LIMIT_MESSAGE_PATTERN` ×2 | rotation and run report
each kept a copy |
| **−** | `RETRYABLE_OPENAI_ERROR_CODES` ·
`TERMINAL_AUTHORIZATION_ERROR_CODES` | the reader's kinds |
| **+** | `quota` in code-sdk `ErrorType` | a quota can't be waited out
|
| **~** | `MastraErrorPart['error']` | keeps `codes` and the provider's
`reason` for a reload |
what callers now import from `@mastra/core/error`
`classifyProviderError(error)` ·
`providerErrorReason(error)` · `providerRequestId(error)` ·
`providerModelId(error)` · `toPersistedErrorIdentity(error)` ·
`PROVIDER_CALL_ERROR_NAME` · `type ProviderFailureKind`
### Decisions
- **overflow wording outranks a 5xx** — a gateway relaying `prompt is
too long` gets compacted, not retried; one rule in `provider-error.ts`
to drop.
- **a caller's numeric `status` outranks wording** — the reader ignores
`status`, which Octokit and MCP errors also carry, so rotation and
`parseError` read it first; a 503 saying `weekly limit` retries instead
of burning an account.
- **only a provider's own sentence is saved** — the saved `reason` comes
from an HTTP response or a stream frame, never from another error's
`detail`, which can name a database row.
### Not verified
- [ ] an app on `@mastra/core` 1.80.0-alpha.0 to alpha.4: the repo's
`-0` floor admits them and they predate the reader, as with `@mastra/pg`
on main; `check:core-imports` passes for server, memory and code-sdk
against this branch's core packed as 1.80.0
- [ ] `changed-tests` stays red: the deployer's core floor moves with no
monorepo E2E change, as on #28417
- [ ] account rotation against real provider accounts: the
`account-rotation`, `account-routing-targeted` and `pack-fallback` TUI
E2E pass with HTTP 429s through the real AI SDK, not a live account
- [ ] the web card after a reload with a real Codex `server_error`
frame: fixtures only
---
> ██████████████████ **source** `+304 −455` — net −151
> █████████████ **tests** `+399 −140`
> ███ **changeset** `+112`
> █ **package.json** `+20 −20` — core peer floor 1.80: server, memory,
agent-builder and editor import the reader
> █ **docs** `+10 −6`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Different parts of the project could interpret the same provider error
in different ways. This change gives them one shared reader so retries,
account rotation, saved errors, and user-facing reports handle those
errors more consistently.
## What changed
- Added provider-error classification and extraction helpers to
`@mastra/core/error`. They read provider codes, reasons, request IDs,
and model IDs from responses and wrapped errors.
- Updated retry handling, account rotation, observational-memory
context-overflow recovery, server error serialization, Factory reports,
and TUI error mapping to use the shared reader.
- Saved errors can include provider codes and reasons. Persisted
provider text is capped at 2,000 characters. Factory failed-run reports
use the provider reason when available and cap the report text at 400
characters.
- Configured retry matchers now run before built-in matchers. Built-in
retry handling excludes credential and exhausted-quota failures.
- Raised the minimum `@mastra/core` peer dependency to 1.80.0 across
affected packages and deployers.
## Verification and limitations
The supplied notes report that `check:core-imports` at the 1.80 floor is
unverified. They also report that `changed-tests` remains red after the
deployer core-floor change. Account rotation against real provider
accounts and web-card behavior after reloading a real Codex
`server_error` frame were not verified; unit tests and fixtures were
used instead.
Review finding counts are unavailable because no current review findings
were supplied.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Lint now requires `import type` for imports used only as types, as
`oxlint.config.ts` always intended. The two rules have matched no files
since mastra-ai/mastra#20173 broke their override's glob, so the repo
drifted into mixing `import { type X }`, `import { X }` for types, and
`import type`. This turns them back on and fixes the existing imports.
No runtime behavior changes.
## What changed
- `import/consistent-type-specifier-style` and
`typescript/consistent-type-imports` go from `off` to `error`.
- 186 files: type-only imports become `import type { … }`, split from
value imports where a statement had both. Done with `oxlint --fix` plus
6 files the fixer left with inline `type` specifiers, then `oxfmt`.
- `disallowTypeAnnotations` is now `false`: `typeof import('x')` is
already type-only, and 97 of its 112 uses are the
`vi.importActual<typeof import('./x')>()` pattern in tests.
## Could this change behavior?
Only where a package keeps imports at runtime (`verbatimModuleSyntax`,
via `tsconfig.node.json`) and a statement became fully `import type`,
since that drops the module load. That happens in 18 places: 11 in
tests, and in source `GithubAppIdentity` (factory), `Workspace`,
`SpanType`, `Knowledge` and `WORKSPACE_TOOLS` (core), `Observable` from
`rxjs` (nestjs), and `zod` / `@mastra/mcp` in the server adapter test
suite. None of those modules run code at load time.
## Scope
The other rules the broken glob turned off (`no-unused-vars`,
`no-console`/`no-debugger`, `ban-ts-comment`, `no-require-imports`, the
test-file import ban) stay off for their own PRs.
## Testing
1. `pnpm lint`: passes (the 13 `only-export-components` warnings are
already on `main`).
2. `pnpm turbo build` for the 34 changed packages and `typecheck` for
the ones that have it: pass.
3. The test files that lost a runtime import: pass (core, server,
observability, factory, voice).
## Description
A command that printed a very large amount of output could crash the
whole agent run with `RangeError: Invalid string length`. The built-in
`executeCommand()` that `MastraSandbox` creates kept all stdout and
stderr (`maxRetainedBytes` defaulted to `Infinity`). Once the retained
output grew past V8's maximum string length, joining it threw from
inside the stdout event handler, where nothing could catch it.
This PR:
- **Bounds the default.** `executeCommand()` now keeps the newest 1 MiB
per stream, the same default `processes.spawn()` already uses. Results
report `stdoutTruncated` / `stdoutDroppedBytes` (and the stderr
equivalents). Streaming callbacks still receive every chunk.
- **Makes complete output safe.** Callers can still pass
`maxRetainedBytes: Infinity` to keep everything, up to 256 MiB per
stream. If a command prints more than that, it is killed and
`executeCommand()` / `handle.wait()` rejects with
`ProcessOutputLimitError` instead of crashing the process or returning
partial output.
- **Tells the model.** `execute_command` and `get_process_output` now
prefix a note when the start of a stream was dropped, so the model
doesn't read the newest output as all of it.
- **Keeps full-output callers complete.** `SandboxFilesystem` in
`@mastra/code-sdk` (base64 file reads, listings, grep), `runInSandbox`
in `@mastra/deployer-sandbox`, and the Factory workspace listing and
change-list commands parse their whole output, so they pass
`maxRetainedBytes: Infinity`.
## Testing
- Reproduced the crash with a real `LocalSandbox` command printing 600
MB. With `Infinity` it used to throw the uncaught `RangeError`; it now
rejects with `ProcessOutputLimitError`. With the default, it finishes
keeping the newest 1 MiB with the truncation fields set.
- New unit tests cover the bounded default, the 256 MiB limit (using a
small injected limit), the kill-and-reject path, the dropped-output
note, and each caller's opt-in. Each test fails without its change.
- Core workspace tests, `@mastra/code-sdk`, `@mastra/deployer-sandbox`
and Factory route tests pass. Typecheck and lint are clean.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Commands can produce more text than the system needs to keep. This
change keeps the newest 1 MiB by default, while letting streaming
callbacks receive all output and allowing selected callers to request
complete output.
## Changes
- `sandbox.executeCommand()` now retains the newest 1 MiB of stdout and
stderr by default. Results include truncation and dropped-byte details.
- Requests for complete output with `maxRetainedBytes: Infinity` have a
256 MiB limit per stream. If a stream exceeds the limit, the process is
killed and `executeCommand()` or `handle.wait()` rejects with
`ProcessOutputLimitError`.
- The `execute_command` and `get_process_output` tools now note when the
start of stdout or stderr was dropped.
- `SandboxFilesystem`, `runInSandbox`, and Factory workspace listing and
change-list commands request complete output.
## Validation
The PR description reports that the relevant core workspace, code SDK,
deployer sandbox, and Factory route tests pass, with typecheck and lint
clean. These results were not independently verified here.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: remy-builder[bot] <324360501+remy-builder[bot]@users.noreply.github.com>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
## @mastra/core@1.78.0-alpha.0
### Minor Changes
- Added `scopes` to agents: the addresses a run acts as, written as
`<type>:<value>` (for example `org:acme`, `resource:user-123`,
`thread:conversation-123`).
([#26593](https://github.com/mastra-ai/mastra/pull/26593))
**Setting scopes.** Pass them per call on `stream`, `generate`,
`network`, `sendMessage`, `queueMessage` and `sendSignal`, set them on
the agent, or set them from trusted middleware with the new
`MASTRA_SCOPES_KEY` request context key. Mastra combines all three. Read
an agent's configured scopes with `agent.getScopes()`.
**Memory.** Memory reads its resource and thread from `resource:` and
`thread:` scopes, in addition to `memory.resource`, `memory.thread` and
the existing request context keys. If they name different values, the
call throws a 400 error instead of silently picking one. Runs with no
scopes from any source behave as before.
```ts
const agent = new Agent({
id: 'support',
model: 'openai/gpt-5-mini',
memory: new Memory(),
scopes: ({ requestContext }) => {
// Set by your auth middleware. Request bodies can fill unreserved keys,
so only read trusted ones.
const orgId = requestContext.get('org-id');
return orgId ? [`org:${orgId}`] : [];
},
});
// Before
await agent.generate('Hi', { memory: { resource: 'user-123', thread:
'conversation-123' } });
// After
await agent.generate('Hi', { scopes: ['resource:user-123',
'thread:conversation-123'] });
```
**Nested calls.** Tools, processors and subagents see the run's other
scopes (for example `org:acme`) under `MASTRA_SCOPES_KEY`, but not its
`resource:` and `thread:` scopes, so nested agent calls can choose their
own thread.
**Suspended runs.** Suspended runs keep their scopes when resumed: a
resume may repeat some or all of them but cannot add new ones.
**Upgrading.** Upgrade `@mastra/server` together with this release.
While an older server is registered, agents refuse scopes from the call
and the request context with an `AGENT_SCOPES_SERVER_OUTDATED` error
(HTTP 400); the agent's own `scopes` option still applies. This
detection relies on the server registering itself with Mastra, which
`@mastra/server` has done since `1.0.0-beta.5`. Servers older than that
— and custom server adapters that never call `mastra.setMastraServer()`
— are indistinguishable from no server at all, so they are not detected:
upgrade them rather than relying on the guard.
Runs suspended before this release have no recorded scope set; resuming
one adopts the scopes supplied at resume time (the same trust checks as
a fresh run apply) instead of rejecting them. Runs suspended after the
upgrade record their set — including the empty set — and a resume may
not add to it.
### Patch Changes
- Fixed durable recovery observers hanging when recovery fails before
the stream starts.
([#26918](https://github.com/mastra-ai/mastra/pull/26918))
- Fixed background task events leaking across resources. Previously,
calling `BackgroundTaskManager.stream()` without a `resourceId`
delivered every resource's task events, including tool arguments and
results. Without a `resourceId`, `stream()` now only delivers tasks that
have no resource. To subscribe to every resource, pass `allResources:
true`: ([#26895](https://github.com/mastra-ai/mastra/pull/26895))
```ts
const events = mastra.backgroundTaskManager.stream({ agentId:
'my-agent', allResources: true });
```
The `/background-tasks`, `/background-tasks/stream` and
`/background-tasks/:backgroundTaskId` routes now use the resource from
the request context. A resource-scoped caller only sees its own tasks:
requesting a different `resourceId` returns 403, and fetching another
resource's task returns 404. An empty resource id in the request context
is rejected with 403. Requests without a resource in the request context
keep access to all resources.
## @mastra/client-js@1.54.1-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/react@1.10.1-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/client-js@1.54.1-alpha.0
## @mastra/deployer-cloud@1.78.0-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/deployer-cloudflare@1.2.37-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/deployer-netlify@1.2.37-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/deployer-sandbox@0.3.22-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/deployer-vercel@1.2.37-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/longmemeval@1.1.37-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/opencode@0.1.37-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/factory@0.22.1-alpha.0
### Patch Changes
- Fixed runs failing with "Factory source-control repository not found."
after a repository's source-control connection was reinstalled. When a
card's repository is linked but turned off in the Factory's environment,
the error now names the repository and says to turn it on under Settings
→ Environment.
([#26970](https://github.com/mastra-ai/mastra/pull/26970))
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/code-sdk@1.13.1-alpha.0
## create-factory@0.2.10-alpha.0
### Patch Changes
- Updated dependencies
[[`27b03c3`](27b03c3b61)]:
- mastra@1.34.2-alpha.0
## @mastra/code-sdk@1.13.1-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## mastracode@0.47.1-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/code-sdk@1.13.1-alpha.0
## mastra@1.34.2-alpha.0
### Patch Changes
- Fixed new Factory sessions showing "Failed to load messages: Thread
not found" while the session's environment is still starting. The
session shows an empty history until it is ready, then loads it,
including after a page reload.
([#26970](https://github.com/mastra-ai/mastra/pull/26970))
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## @mastra/deployer@1.78.0-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/mcp-docs-server@1.3.8-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/playground-ui@63.0.1-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/client-js@1.54.1-alpha.0
- @mastra/react@1.10.1-alpha.0
## @mastra/server@1.78.0-alpha.0
### Patch Changes
- Agent scopes support:
([#26593](https://github.com/mastra-ai/mastra/pull/26593))
- Agent routes ignore `scopes` in request bodies (including
`ifIdle.streamOptions.scopes`), and `mastra__scopes` is a reserved
request context key.
- Set scopes from trusted server middleware instead:
```ts
import { MASTRA_SCOPES_KEY } from '@mastra/core/request-context';
server: {
middleware: [async (c, next) => {
c.get('requestContext').set(MASTRA_SCOPES_KEY,
[`org:${orgIdFromAuth(c)}`]);
await next();
}],
}
```
- A conflicting `resource:` or `thread:` scope returns a 400 error.
- With an older `@mastra/server` registered, agent calls that pass
scopes — from the call or the request context — fail with
`AGENT_SCOPES_SERVER_OUTDATED` (HTTP 400). Scopes configured on the
agent itself still work. Upgrade the server to lift the restriction.
- Fixed background task events leaking across resources. Previously,
calling `BackgroundTaskManager.stream()` without a `resourceId`
delivered every resource's task events, including tool arguments and
results. Without a `resourceId`, `stream()` now only delivers tasks that
have no resource. To subscribe to every resource, pass `allResources:
true`: ([#26895](https://github.com/mastra-ai/mastra/pull/26895))
```ts
const events = mastra.backgroundTaskManager.stream({ agentId:
'my-agent', allResources: true });
```
The `/background-tasks`, `/background-tasks/stream` and
`/background-tasks/:backgroundTaskId` routes now use the resource from
the request context. A resource-scoped caller only sees its own tasks:
requesting a different `resourceId` returns 403, and fetching another
resource's task returns 404. An empty resource id in the request context
is rejected with 403. Requests without a resource in the request context
keep access to all resources.
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/elysia@0.1.18-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/express@1.5.22-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/fastify@1.5.22-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/hono@1.7.20-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/koa@1.7.22-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/nestjs@0.2.37-alpha.0
### Patch Changes
- The NestJS server marks itself as reserving agent scopes, like the
other server adapters. Its routes already ignore `scopes` in request
bodies and treat `mastra__scopes` as reserved, so agents accept scopes
from your code and middleware when served through NestJS.
([#26593](https://github.com/mastra-ai/mastra/pull/26593))
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
## @mastra/next@0.2.36-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
- @mastra/hono@1.7.20-alpha.0
## @mastra/tanstack-start@0.2.36-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/server@1.78.0-alpha.0
- @mastra/hono@1.7.20-alpha.0
## @mastra/inngest@1.10.6-alpha.0
### Patch Changes
- Inngest agents honor agent `scopes` when used with a `@mastra/core`
release that supports them. Memory identity comes from `resource:` and
`thread:` scopes, tools and processors see the other scopes, and a
resumed run keeps the scopes it started with. Resuming with a scope the
run did not hold throws an error and leaves the suspended run untouched.
Scopes in the agent's `defaultOptions` count as the agent's own scopes,
not the caller's.
([#26593](https://github.com/mastra-ai/mastra/pull/26593))
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
## @mastra/temporal@0.4.16-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/deployer@1.78.0-alpha.0
## create-mastra@1.34.2-alpha.0
## @internal/playground@1.34.2-alpha.0
### Patch Changes
- Updated dependencies
[[`0b1ea6c`](0b1ea6ca62),
[`33eb344`](33eb344ebf),
[`5d12fbf`](5d12fbfcd7)]:
- @mastra/core@1.78.0-alpha.0
- @mastra/client-js@1.54.1-alpha.0
- @mastra/react@1.10.1-alpha.0
- @mastra/playground-ui@63.0.1-alpha.0
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>