mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
5,146 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d60ba71be0 | chore: version - exit prerelease mode | ||
|
|
18168d518c |
feat(playground): show the built-in MCP server in Studio (#29932)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
4ba2bdef89 |
feat(server): memory, observability and agent builder MCP toolsets (#29931)
## Description Adds four toolsets to the built-in MCP server at `/api/mcp`: - `memory`: threads, messages, memory search, and Observational Memory. `get_observations` can wait for pending Observational Memory work, for example right after `call_agent`. - `observability`: trace and span queries, logs, and trace trajectories. - `observability_analytics`: `analyze_metrics`, `analyze_scores`, and `analyze_feedback`, plus metric name and label lookups. - `stored_agents`: list allowed models, and create, read, and update stored agents. With these, an MCP client such as Claude Code can create an agent, talk to it, read what it remembered, and explain a slow trace. ### Behavior - **On by default, shown only when supported.** Each toolset appears only when the app has the matching capability (a memory-enabled agent, an observability store that supports the queries, an editor for stored agents). Apps that don't set `server.mcp.toolsets` get these tools on upgrade, including write tools. Set `toolsets` to keep the previous set, or `readOnly: true` to drop writes. The changeset says this. - **Same checks as HTTP.** Every tool dispatches through its HTTP route, so authentication, RBAC, FGA, thread ownership, and agent visibility apply unchanged. No MCP caller gets more access than the same caller over HTTP. - **Observability isn't scoped per user.** Anyone with `observability:read` sees all traces, as over HTTP. The docs show how to leave those toolsets out. - **Builder model policy.** When the agent builder restricts models, `create_stored_agent` and `update_stored_agent` check the model the agent runs (`provider` and `name`, in every conditional variant; other keys on `model` are rejected), models named in `defaultOptions` such as `structuredOutput.model`, enabled fallback models (`modelList`), memory models, input and output processor models, and the defaults they fall back to. Anything the policy can't check is rejected. The HTTP stored-agent routes don't apply this check. Agents created or updated over MCP are published immediately (`update_stored_agent` defaults `autoPublish` to `true`). - **Results fit MCP client limits.** `get_trace` returns light span records with every span id, and `get_span` returns one span in full. Long lists are cut to fit, with a note on how to get the rest, and a single oversized item has its long values shortened (ids are never cut). - **Errors.** Bad `analyze_*` and `list_metric_names` arguments return 400. A failed observability store lookup is retried on the next request instead of hiding the observability tools until restart. Stacked on #29930. ## Test plan - `@mastra/server`: unit tests for the toolsets, capability detection, result sizing, and schemas. - Shared adapter suite (`builtin-mcp-toolsets-test-suite`) on Hono, Express, Fastify, Koa, Elysia, and NestJS: memory ownership compared with HTTP on the same request, read-only mode, analytics dispatch, and argument errors. Hono also runs observability tests against in-memory, LibSQL, and DuckDB stores. - `@mastra/editor` integration tests for the builder model policy across `model` (static and conditional), `defaultOptions`, fallback models, memory, and processors. They need no provider API keys. - Run end to end with two users over MCP and HTTP, and with Claude Code. --------- Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
27705673f2 |
feat(server): OAuth discovery and audience checks for the built-in MCP endpoint (#29930)
## Description
Lets MCP clients such as Claude Code sign in to the built-in `/api/mcp`
endpoint with OAuth instead of a pasted token. The endpoint tells
clients where to sign in (RFC 9728 protected-resource metadata) and can
reject tokens issued for a different API (audience check).
```ts
new Mastra({
server: {
auth: new MastraJwtAuth({
jwksUri: 'https://auth.example.com/.well-known/jwks.json',
issuer: 'https://auth.example.com/',
}),
mcp: { oauth: { resource: 'https://my-app.example.com/api/mcp' } },
},
});
```
### Behavior changes
**OAuth discovery for `/api/mcp`** (`@mastra/server`, every server
adapter including NestJS)
- When `server.auth` is set and the built-in MCP server is on, a `401`
from `/api/mcp` carries `WWW-Authenticate: Bearer
resource_metadata="…"`. `error="invalid_token"` is added only when a
token was sent (RFC 6750 §3).
- Metadata is served publicly at
`/.well-known/oauth-protected-resource/api/mcp` and
`/.well-known/oauth-protected-resource`, with `Cache-Control: no-store`.
- The document lists `resource`, `authorization_servers`, optional
`scopes_supported`, and `bearer_methods_supported: ['header']`. Without
`oauth.resource`, `resource` is derived from the request origin.
- The challenge, metadata routes and audience check apply only to
`/api/mcp`. Other routes are unaffected.
**Audience check** (`server.mcp.oauth.resource`)
- When set, the token audience must include this exact value, or the
request gets 401.
- An invalid value (non-URL, or a non-loopback `http://` URL) turns
discovery off and logs an error, but the audience check still runs
against it. Requests fail closed until the value is fixed.
- A provider that can't check audience (no `verifyAudience`, for example
`SimpleAuth` API keys) is accepted by default. The server logs a startup
warning on adapters built on `MastraServer`, not on NestJS.
- `requireAudience: true` (opt-in, only valid together with `resource`)
rejects those requests on `/api/mcp` with 401 `invalid_token`. Inside
`CompositeAuth`, only requests accepted by such providers are rejected.
Without `resource`, nothing changes.
**Config and provider hooks** (`@mastra/core`)
- New `server.mcp.oauth` config: `resource`, `requireAudience`,
`authorizationServers`, `scopesSupported`.
- Two new optional auth-provider methods:
- `getOAuthMetadata()` advertises the provider's authorization server.
- `verifyAudience()` checks the token audience.
- `CompositeAuth` combines the authorization servers of its providers.
It checks the audience with the provider that accepted the token, and
rejects when that provider can't be determined. The new
`getAuthenticatedProvider(user)` returns that provider.
**Providers**
| Provider | Advertises its authorization server | Checks audience
against `oauth.resource` |
|---|---|---|
| `MastraJwtAuth` | Yes, its `issuer` | Yes |
| Auth0 | Yes, the tenant | Yes |
| Clerk | Yes, the Frontend API | No |
| Okta | Yes, the issuer | No: Okta already enforces its own `audience`
(`OKTA_AUDIENCE`) |
| Supabase | Yes, `<url>/auth/v1` (requires Supabase's OAuth 2.1 server)
| No |
`MastraJwtAuth` gains `jwksUri` and `issuer` options
(`JWT_AUTH_JWKS_URI`, `JWT_AUTH_ISSUER`), so it can verify tokens signed
by an identity provider. JWKS keys are restricted to their key type, so
HMAC tokens forged with the public key are rejected.
**JWT subject as user id** (`@mastra/auth`, Auth0, Clerk)
- When a token has no `id` claim, the user's `id` is now set to `sub`.
Existing `id` claims are kept.
- Standard OIDC access tokens only carry `sub`. Before this change, RBAC
never loaded roles for these users, so every protected route returned
`403 Missing required permission`.
- Unless `mapUserToResourceId` is set, this also scopes data for these
users:
- **Owned records** (stored agents, skills, workspaces and other owned
records): each user sees their own records plus public ones. Admin
permissions keep the full list.
- **Tool-provider connections:** per-author connections move from the
shared `default` owner to the user's `sub`. Existing connections need
reconnecting, or set `mapUserToResourceId: () => 'default'` to keep the
old shared behavior.
- **Feedback:** recorded with `sub` as the user id.
- The changeset describes all of these effects.
**Test suite** (`@mastra/server-adapters-test-suite`)
- New `createBuiltinMCPOAuthTestSuite`.
- The package now has `@mastra/auth` and `jose` as peer dependencies.
Stacked on #29929.
## Test plan
- `packages/server`: `src/server/mcp/oauth.test.ts` and
`oauth-without-mcp.test.ts`. They cover metadata, the challenge format,
resource validation, failing closed on an invalid `resource`, and
discovery working without `@mastra/mcp` installed.
- `packages/auth` `jwt.test.ts`:
- JWKS and issuer validation
- string and array `aud`
- an algorithm-confusion token that is HS256-signed with the real RSA
public key PEM and must be rejected
- `sub` used as `id`
- `packages/core` `composite-auth.test.ts`: per-provider audience
delegation, rejection when the authenticating provider is unknown, and
`getAuthenticatedProvider`.
- `auth/auth0`, `auth/clerk`, `auth/okta`, `auth/supabase` unit tests.
- `createBuiltinMCPOAuthTestSuite` on Hono, Express, Fastify, Koa and
Elysia, plus the NestJS equivalent. It checks:
- the challenge, and fetching the advertised metadata URL
- audience accept and reject, including for an invalid `resource`
- `requireAudience`:
- `SimpleAuth` + `resource`: 200 by default, 401 in strict mode
- a JWT with a matching audience: 200 in strict mode
- a mixed `CompositeAuth`: only the API key is rejected
- RBAC with a token that carries only `sub`
- that a `sub`-only user can't list another user's private stored agent
- `tsc --noEmit` and `oxlint` on the touched packages, plus docs `pnpm
check` and Vale.
- Manual run end to end with Claude Code against a local identity
provider: discovery, client registration, PKCE login, and two users with
different roles.
---------
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
|
||
|
|
171e27355f |
fix(code-sdk): fire SessionStart again when a session binds a different thread (#30223)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
392c7b69d5 |
feat(server): built-in MCP endpoint for agents, workflows and tools (#29929)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
25ba8bae0e |
docs(memory): rewrite the Observational Memory guide (#30213)
Co-authored-by: remy-builder[bot] <324360501+remy-builder[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
d05afc4a90 |
refactor(server): shared route authorization and in-process dispatchRoute across adapters (#29928)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
649ac25a61 |
docs(studio): remove outdated Studio overview and deployment details (#30220) | ||
|
|
c0d3bfdc43 |
feat: pass the authenticated user to DynamicArgument callbacks (#28612)
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>
|
||
|
|
731b66498c |
docs(mcp): remove prebuilt Mastra apps section (#30209)
## Description Removes the "Use prebuilt Mastra apps" section from `docs/connections/mcp`, along with `@mastra/mcp-apps-components` in the page's `packages` frontmatter. The package exists to support Playground UI MCP App components and shouldn't be documented as a user-facing package yet. ## Related issue(s) None. Requested internally in Slack (#growth-pmm). ## Type of change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Code refactoring - [ ] Performance improvement - [ ] Test update ## Checklist - [ ] I have linked the related issue(s) in the description above - [x] I have made corresponding changes to the documentation (if applicable) - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] I have addressed all Coderabbit comments on this PR Link to Devin session: https://app.devin.ai/sessions/e41299f3bd58441b9d227362b56641e1 Open in Devin Desktop: https://app.devin.ai/desktop/session/e41299f3bd58441b9d227362b56641e1?variant=devin <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> **ELI5:** The docs page for MCP no longer talks about a ready-made app package. That package is still being built for internal use, so it should not appear in public docs yet. ## Summary This change removes user-facing documentation for `@mastra/mcp-apps-components` from the MCP docs page. ## Changes - `docs/src/content/en/docs/connections/mcp.mdx`: Removes the "Use prebuilt Mastra apps" section. This section explained how to install and use the package's prebuilt greeting app. Removes `@mastra/mcp-apps-components` from the page's `packages` frontmatter. ## Scope - Files changed: 1 - Lines added: 0 - Lines removed: 46 - The rest of the MCP Apps documentation is unchanged. ## Rationale The package supports Playground UI MCP App components. The team does not yet want to document it as a user-facing package. ## Public API No exported or public declarations change. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: paul <paul@mastra.ai> |
||
|
|
79ff445aca |
fix(rag): reject JSON chunk sizes that stall string splitting (#30186)
## Summary - Require JSON chunk `maxSize` of at least 21 in strategy validation and direct transformer construction, preventing zero-length string splits from stalling chunking. - Add regressions for invalid integer and fractional limits and verify long strings reconstruct at the supported boundary. - Include a patch changeset for `@mastra/rag`. ## Test plan - `cd packages/rag && ./node_modules/.bin/vitest run src/document/document.test.ts --reporter=dot` (167 passed) - `./node_modules/.bin/tsc --noEmit -p packages/rag/tsconfig.json` - Type-aware oxlint for changed files; Prettier check; `git diff --check` Fixes #30166 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> **ELI5:** The JSON text splitter could get stuck in an endless loop when a user set a small chunk size. This change rejects those small sizes with a clear error, so the splitter never hangs. ## Summary This change stops JSON chunking from hanging when `maxSize` is too small. The splitter subtracts a fixed overhead of 20 from `maxSize` and floors the result. At `maxSize` 20, the split point is zero. The splitter then never consumes input. Fractional values between 20 and 21 have the same problem. The change sets a minimum JSON `maxSize` of 21. It applies this minimum in two places: - **Option validation** (`packages/rag/src/document/validation.ts`): The JSON chunk options schema adds an optional `maxSize` field. It accepts the field only when the value is at least 21. - **Transformer constructor** (`packages/rag/src/document/transformers/json.ts`): `RecursiveJsonTransformer` throws a `RangeError` when `maxSize` is not finite or is below 21. Other chunking strategies keep their existing size rules. ### Documentation - `docs/src/content/en/reference/rag/chunk.mdx` states that the JSON strategy's `maxSize` is a target maximum for each chunk. It must be at least 21. Long values nested in objects can exceed it. - A patch changeset for `@mastra/rag` describes the new minimum. ### Tests (`packages/rag/src/document/document.test.ts`) - Adds cases that expect `maxSize` values `0.5`, `20`, and `20.9` to be rejected. The cases cover both `MDocument.chunk` and direct transformer construction. The expected error matches `maxSize.*21`. - Adds a case that splits a 100-character JSON string with `maxSize: 21`. The test checks that the output has multiple chunks. It also checks that the parsed string values rejoin to the original text. ### Behavior change Callers that pass a JSON `maxSize` below 21 now receive a configuration error. Before this change, those calls were accepted and could hang. Default JSON chunking remains valid. ### Reported validation (not verified in this summary) The PR description reports these checks: - `vitest run src/document/document.test.ts`: 167 passed. - `tsc --noEmit` for `packages/rag`. - Type-aware oxlint on changed files, Prettier check, and `git diff --check`. Diff size: 5 files changed, 38 lines added, 1 line removed. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
da717f489c |
Fix GraphRAG leaking documents across reused tool requests (#30185)
## Summary - Rebuild the GraphRAG graph from each request’s retrieval results so tenant-specific indexes cannot reuse a previous request’s documents. - Return empty context and sources when retrieval yields no candidates. - Add a real LibSQL and embedding-server regression covering sequential, empty, and concurrent requests, plus a patch changeset. ## Test plan - `pnpm build:rag` - `pnpm test:rag` (454 tests) - `pnpm exec tsc --noEmit -p packages/rag/tsconfig.json` - `pnpm --filter ./packages/rag lint` - `pnpm exec prettier --check packages/rag/src/tools/graph-rag.ts packages/rag/src/tools/graph-rag-isolation.test.ts .changeset/graph-rag-request-isolation.md` Fixes #30168 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> **ELI5:** A search helper that is reused can return a document from an earlier user's search. This change makes the helper build its answer only from the current search. Each request now gets results for its own search. ## Summary This change fixes a data-isolation defect in the GraphRAG tool that `createGraphRAGTool` creates in `@mastra/rag`. Linked issue `#30168` reports the defect. The tool kept one `GraphRAG` instance and an `isInitialized` flag across executions. Later requests that selected a different index could still receive documents from the first execution. ## Changes - `packages/rag/src/tools/graph-rag.ts` (+32/-37): - Removes the `GraphRAG` instance and the initialization flag that persisted across executions. - Returns empty context and sources when vector search finds no candidates. - Otherwise, builds a new graph from that execution's retrieved chunks and embeddings, then traverses it. - Keeps graph-build logging, tracing, and error propagation. - `packages/rag/src/tools/graph-rag-isolation.test.ts` (+84/-0): Adds a Vitest integration test. The test uses tenant-specific and empty vector indexes. It serves an `LLMock` through a local HTTP proxy. It checks that: - A request returns only the document from its selected index. - An empty index returns empty results. - Concurrent requests stay isolated. - `.changeset/graph-rag-request-isolation.md` (+5/-0): Declares a patch release for `@mastra/rag`. - `docs/src/content/en/reference/rag/graph-rag-guide.mdx` (+1/-1): States that each graph query tool execution builds its graph from that request's retrieved chunks. The guide no longer says that later queries reuse the first execution's graph. No exported or public declarations change. ## Tradeoff Each execution now builds a graph. The linked issue states that this adds work per request. The request-specific candidates require this work. A future cache would need correct candidate and scope keys. ## Verification Not available. The PR lists planned checks: `pnpm build:rag`, `pnpm test:rag`, a TypeScript check, lint, and a Prettier check. No completed results for these checks were supplied. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
72abae68eb |
feat(observability): export span-local originating error counts (#30088)
## Description Export `errorCount` as failures originating directly on each span. Child failures forwarded through a model step, workflow or agent add no parent count; independent parent failures do. Failed retries remain counted after recovery, and replay does not create new occurrences. No parent/child totals or suspend/resume rollup are maintained. Attribution stays in a WeakMap without modifying user errors. Explicit internal serializers and Inngest memoized operations preserve provenance across boundaries; public workflow results and stored workflow state omit transport metadata. Failures before child execution count on their actual originating span. Excluded spans preserve attribution so their failures cannot be misassigned to visible parents, but excluded failures are absent from exported totals. Retry context stays in the server-only context module, while shared origin utilities use global crypto. Guarded cross-package calls preserve mixed-version startup compatibility. Unsupported accounting and older snapshots remain unknown. Error-free spans do not allocate occurrence sets. Validation: 117 focused observability/workflow/compatibility tests, 23 real Inngest error/retry scenarios and 37 Inngest engine/nested-result checks pass. New regressions reproduced resolver undercounting, excluded-child misattribution and public transport-field leakage before the fixes. Real Inngest tests cover an empty execution graph, unavailable remote child, instrumented child errors, nested propagation, retries, public responses and stored state. Core/observability build, Inngest typecheck, changed-file type-aware lint and CI formatting checks pass. The preceding merge also passed 167 core checks and redaction integration coverage. Playground production builds were verified on Node 24. Docs checks with Vale report no errors (three warnings on unchanged API headings); the CI Vale configuration passes. Standalone observability `tsc` previously reported generic union-call errors in untouched `workflow-control-flow-suite.ts`; package builds and focused tests pass. No production rollout or query-table changes. CI reruns on the new head. ## Related issue(s) Fixes https://linear.app/kepler-crm/issue/OBS-901 Follow-ups: https://linear.app/kepler-crm/issue/OBS-902 and https://linear.app/kepler-crm/issue/OBS-903 Nonblocking review follow-up: https://linear.app/kepler-crm/issue/OBS-905 tracks explicit propagated classification on previously untagged errors and reuse of one Error object across separate foreach iterations. Changesets intentionally remain single sentences per maintainer direction. ## Type of change - [x] New feature (non-breaking change that adds functionality) - [x] Documentation update - [x] Test update ## Checklist - [x] I have linked the related issue(s) in the description above - [x] I have made corresponding changes to the documentation (if applicable) - [x] I have added tests that prove my fix is effective or that my feature works - [ ] I have addressed all Coderabbit comments on this PR <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This change counts each error on the span where it first happened. It keeps the count correct when errors are wrapped, retried, or rebuilt, so one failure is not counted twice. ## Summary - Adds span-local `errorCount` to exported spans. The count covers failures that start directly on that span. - Adds `claimSpanError`, `BaseSpan.recordError`, and `BaseSpan.restoreErrorCount`. Each claim records one occurrence ID on the span. - Ignores propagated failures on the receiving span. Propagated failures count only on their origin span. - Keeps error origin through cause chains, durable tool serialization, and event codecs. - Stores origin metadata in a `WeakMap` for live errors and formatted results. Omits it from public workflow JSON. - Stores occurrence IDs in span snapshots. Rebuilt spans restore them, so replayed attempts are not counted again. - Records failed attempts for default, evented, and Inngest workflow retries. Each attempt uses an attempt-scoped occurrence ID. - Reports `errorCount` as unknown when the runtime lacks the claim API or when an older snapshot has no accounting history. - Updates tracing types, the span record schema description, the span reference documentation, and changesets for `@mastra/core`, `@mastra/observability`, `@mastra/client-js`, and `@mastra/inngest`. - Adds tests for repeated reports, retry scopes, concurrent async spans, excluded children, cause-linked errors, tool and agent spans, rebuilt and legacy snapshots, codecs, durable serialization, workflow retries, and ESM/CJS compatibility with an older core build. ## Scope - Parent and child totals are not computed. - Suspend and resume rollups are not computed. - Query-time summation, display, filtering, sorting, and aggregate-table integration are not included. These are tracked in [OBS-902](https://linear.app/kepler-crm/issue/OBS-902) and [OBS-903](https://linear.app/kepler-crm/issue/OBS-903). - Counts reflect observed exported failures only. Filtering, sampling, or loss before export can leave counts incomplete. ## Change size - 32 files changed - 862 lines added - 161 lines removed ## Validation - Completed checks on the current head: not available from the supplied evidence. - Author-reported results, not verified here: - Focused observability tests, codec and durable-serialization checks, and engine and Inngest retry scenarios. - Node 24 builds, 167 core checks, 125 observability and redaction tests, and 19 real Inngest scenarios. - Type-aware lint and `lint:format`. - Known limitations: - A prior monorepo E2E attempt did not run application assertions. Fixture dependency installation failed with a pnpm store ENOENT error. - Earlier runtime tests ran on Node 23.11.0, which is outside the supported engine range. - Standalone observability `tsc` reports errors in an untouched test utility. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
46ce164dde |
fix(factory): recover stuck environment builds and rebuild on saved changes (#30148)
Environment templates could stop rebuilding for good, and changing a
setup command never rebuilt them.
When a build start isn't recorded (for example the process restarts
mid-start), Factory marks the start uncertain and asks the provider for
its build list before building again. Mastra Platform has no build list,
so that mark could never clear: every Build now, schedule and push run
skipped with `unresolved` forever and sessions kept booting an old
template. Now an uncertain start ages out 30 minutes (the build wait
ceiling) after its lease lapsed, Factory logs once that it gave up on
it, and the next trigger builds. A new `build_start_uncertain_since`
column records when the mark started; rows already stuck get stamped on
their next read and recover 30 minutes later.
Saving a template input (setup commands, working directory, settings,
environment repositories, Build variables) also never started a build,
so each new sandbox reran the changed setup command. Saves now start a
build once the project has a template, only when the inputs actually
differ from the last build. Repeated saves don't double-build, and a
change saved during a build is built when that build ends.
Before: a project stuck on `unresolved` stayed on its Oct 28 template,
and a new setup command reran for 40s in every sandbox. After: the stuck
project builds on its next trigger after 30 minutes, and saving the
setup command rebuilds the template.
Tested with red/green tests on LibSQL and Postgres 16 using real storage
and a fake clock, plus route tests for every save path.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
**ELI5:** Sometimes the system got stuck while it prepared a project's
build environment, and it did not try again for a long time. Also,
saving changes to the project's setup did not start a new build. This
change fixes both problems. Stuck builds now recover, and saved changes
now start a new build when they affect the template.
## Overview
This change fixes two problems in Factory environment template builds.
1. **Stuck build starts.** A build start can stay `unresolved` for a
long time when the provider cannot list builds.
2. **Missing rebuild on save.** Saving changed template inputs did not
start a build.
Diff base: `main` at merge base
`
|
||
|
|
f0710446e0 |
feat(observability): sort spans by model and provider (#30096)
Adds ascending/descending `model` and `provider` ordering to
`querySpans()` across Core, server, Client JS, PostgreSQL, DuckDB and
ClickHouse. No schema changes or backfill.
```ts
orderBy: [{ field: 'model', direction: 'asc' }]
```
Sorting uses the dedicated columns before pagination, with
case-sensitive UTF-8 ordering, missing values last, and identity
tie-breakers. String cursors preserve their values and remain bound to
the query and trusted scope. Legacy attribute-based display values
remain available without changing cursor boundaries. Trace/thread sort
fields stay unchanged. The server advertises
`spanQueryModelProviderSort` and rejects unsupported stores.
This PR is API-only. Studio sorting controls and live-refresh changes
are tracked in
[OBS-906](https://linear.app/kepler-crm/issue/OBS-906/add-model-and-provider-sorting-to-spans-explorer).
Enabling those controls needs raw model/provider sorting values
available to the existing head-row merge, including when polls are
ordered by end time; using display values can disagree with database
ordering. The PR has no remaining Playground UI changes or release
entry.
Validation: Core/server tests, real storage conformance across
PostgreSQL, DuckDB and ClickHouse, mixed-core checks, and
Core/server/adapter typechecks passed for the API implementation. After
removing the UI changes, both existing span component/hook suites pass
(52 tests). Changed-file lint and docs checks including CI Vale pass.
A bounded local ClickHouse 26.6.8.7 comparison used 180,000 synthetic
rows, 10,000 matches per tenant, distinct tenants across cases, both
directions and continuation pages, and disabled query/condition caches.
Median CPU was 21.9 ms for start time, 19.4 ms for model, and 21.4 ms
for provider; median query memory was about 4.6 MiB for each (maximum
6.8/8.4/7.2 MiB). These are selection-query measurements on synthetic
OSS data, not a production benchmark.
Part of OBS-896. Platform API support and package pins follow this OSS
merge and snapshot publication. UI enablement is tracked separately in
OBS-906.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
**ELI5:** Trace spans can now be sorted by their model name and provider
name, in both directions. The database does the sorting, so users can
page through the results in the right order.
## Overview
This change adds `model` and `provider` as sort fields for span queries.
It applies to the Core API, the server handlers, and the PostgreSQL,
DuckDB, and ClickHouse stores. The diff has 31 changed files, with 320
lines added and 43 removed.
## Core changes
- `SPAN_QUERY_ORDER_FIELDS` now includes `model` and `provider`.
- `SpanQueryPlanOptions` adds `allowSpanModelProviderOrdering?:
boolean`. Ordering by these fields requires this option.
- Trace and thread queries do not support these fields.
- Cursor validation accepts string or null values for `model` and
`provider`. Timestamp normalization applies only to `startedAt` and
`endedAt`.
- `SpanQuerySelectedRow` adds an optional `cursorSortValue`. Response
construction removes this field from returned spans. It uses the value
for the next-page cursor, and falls back to the row's ordering field
when the value is absent.
- The base storage feature union adds `span-query-model-provider-sort`.
## Server changes
- `assertObservabilitySpanModelProviderSortSupported` returns HTTP 501
with `SPAN_QUERY_UNSUPPORTED` when a store does not declare
`span-query-model-provider-sort`. The check runs before `querySpans` is
called.
- `ObservabilityStorageCapabilities` and its empty default add
`spanQueryModelProviderSort`, which defaults to `false`.
- The capability is reported as supported only when span queries are
supported, the core order fields include both `model` and `provider`,
and the store declares the feature.
- The system capabilities schema adds `spanQueryModelProviderSort:
z.boolean().default(false)`.
- The route handler permits model and provider ordering and performs the
capability check.
## Store changes
- **PostgreSQL:** Sorts by `model` and `provider` use `COLLATE "C"`. The
cursor bounds cast sort values to `text COLLATE "C"` when `stringSort`
is enabled. The feature is advertised only when the core order fields
include both fields.
- **DuckDB:** Sorts by `model` and `provider` use `"C"` collation.
Cursor values cast as strings with the same collation. The feature is
advertised only when the core order fields include both fields.
- **ClickHouse:** `afterCursor` treats `model` and `provider` as
strings. Null rows are included after the cursor for numeric and string
sorts. The feature is advertised only when the core order fields include
both fields.
- Returned `model` and `provider` values may still come from span
attributes. The code comments state that these fallback values are not
used for filtering or sorting.
## Tests and conformance
- Core tests cover ordering gating, rejection in trace and thread
queries, string and null cursor values, and rejection of cursors when
the order, filters, authorization, or scope change.
- Server tests cover the 501 rejection for `durationMs`, `model`, and
`provider` on older stores. They also cover capability parsing and the
capability flag in the system endpoint.
- Shared conformance tests in `stores/_test-utils` cover ascending and
descending pagination at page sizes 1, 2, and 3. They cover empty
strings, missing values, case and Unicode ordering, ties, and filter
exclusion. They also check that missing values sort last and that legacy
attribute values are not treated as dedicated fields.
- Store feature-list tests for ClickHouse, DuckDB, and PostgreSQL expect
the new feature flag.
## Changesets and documentation
- Changesets add minor release notes for `@mastra/core`,
`@mastra/server`, `@mastra/client-js`, `@mastra/duckdb`,
`@mastra/clickhouse`, and `@mastra/pg`.
- The advanced query reference adds the `spanQueryModelProviderSort`
capability row. It documents `model` and `provider` ordering. It states
that the comparison is case-sensitive and that missing values sort last
in both directions.
## Scope and limits
- This diff does not include Studio UI changes. The commit history says
UI enablement is deferred to a separate issue because it needs raw model
and provider values for head-row merging.
- This diff does not include client-js source changes. Its client-js
changeset documents the new sort fields.
- The diff does not include schema changes or backfill.
- The PR description reports these results, which this review did not
run or verify:
- Core and server tests, and real shared-storage conformance and
mixed-core checks, pass.
- Core, server, and adapter typechecks pass. Staged-file lint and docs
checks, including CI Vale, pass.
- 58 Studio and MSW tests pass.
- The full Playground UI typecheck reports four unrelated chart and form
errors, and the library declaration build fails.
- A local ClickHouse 26.6.8.7 comparison with 180,000 synthetic rows
measured median CPU of 21.9 ms for start time, 19.4 ms for model, and
21.4 ms for provider. Median query memory was about 4.6 MiB for each.
These figures are not production measurements.
- Platform backend and UI wiring, and package pins, remain under
OBS-896.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
|
||
|
|
ba2529c209 |
docs(models): explain when to use custom gateways and the base class (#30066)
## Description The custom gateways guide showed a plain-object gateway and a `MastraModelGateway` subclass. It didn't explain when to use a custom gateway or why you'd extend the class. Changes: - `docs/src/content/en/models/gateways/custom-gateways.mdx` - New "When to use custom gateways" section, which replaces the "Create custom gateways to support" list. - It describes a custom gateway as the way to connect Mastra to open-weight models you run yourself, such as gpt-oss, Llama, Gemma, Mistral, Qwen, or DeepSeek. - It lists when self-hosting fits: compliance rules on sending data to third parties, per-token pricing that costs more than running your own GPUs, fine-tuned models, model versions that only change when you upgrade, and offline, air-gapped, or edge deployments. - It notes what the gateway adds: typed model IDs and a Studio model picker, per-call credential resolution, and Studio filtering with `AUTO_BLOCK_EXTERNAL_PROVIDERS`. - For a single OpenAI-compatible endpoint, it points to `url` in the model config instead. It also says to set `apiKey` there, because Mastra doesn't read environment-variable keys for `url` models. - New "Choose a plain object or a class" subsection. Both forms behave the same at runtime, because the base class defaults for `getId()`, `shouldEnable()`, `handlesModel()`, and `serializeForSpan()` match the fallbacks in `gateway-helpers.ts`. A class makes sense when you need constructor options, private state, or several instances. - Replaced the class example with one that takes optional `id`, `baseURL`, and `apiKey` constructor options. Added a two-instance example with distinct IDs, because `GatewayManager` deduplicates gateways by ID. Both examples now forward `headers` in `resolveLanguageModel()`. - "Showing only custom gateways in Studio" now says the filter also applies to `GET /agents/providers`. It only changes which providers are listed, and doesn't stop agents from calling other providers in code. - `docs/src/content/en/docs/studio/overview.mdx`: the model picker section now mentions `AUTO_BLOCK_EXTERNAL_PROVIDERS` and links to the custom gateways section. ## Related issue(s) Docs follow-up from a Slack question about `MastraModelGateway`. ## Type of change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Code refactoring - [ ] Performance improvement - [ ] Test update ## Checklist - [ ] I have linked the related issue(s) in the description above - [x] I have made corresponding changes to the documentation (if applicable) - [ ] I have added tests that prove my fix is effective or that my feature works - [x] I have addressed all Coderabbit comments on this PR Link to Devin session: https://app.devin.ai/sessions/922f1f27155a4c858ce0e76079f78b2f Open in Devin Desktop: https://app.devin.ai/desktop/session/922f1f27155a4c858ce0e76079f78b2f?variant=devin --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: paul <paul@mastra.ai> |
||
|
|
686c178917 |
fix(voice): replace retired default OpenAI Realtime model (#30183)
## Summary - Default new OpenAI Realtime voice connections to `gpt-realtime-2.1-mini` instead of the retired preview model. - Align the constructor examples, README, and voice integration documentation with the new default. - Cover default and explicit model selection with a real local WebSocket handshake regression test and a patch changeset. ## Test plan - `pnpm turbo build --filter="@mastra/voice-openai-realtime^..."` - `pnpm --dir voice/openai-realtime-api test` (70 tests) - `pnpm --dir voice/openai-realtime-api exec tsc --noEmit --project tsconfig.json` - `pnpm --dir voice/openai-realtime-api lint` - `pnpm --dir voice/openai-realtime-api build` Fixes #29722 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> **ELI5:** The OpenAI voice connector picked an old model by default, and OpenAI has shut that model down. This change makes the connector pick a current model by default. Users who set their own model still get that model. **Overview** This change replaces the default OpenAI Realtime model in `@mastra/voice-openai-realtime` with `gpt-realtime-2.1-mini`. The previous default was `gpt-4o-mini-realtime-preview-2024-12-17`. Linked issue `#29722` reports that OpenAI lists this snapshot as shut down. **Changes by file (5 files, +36/-8 lines)** - `voice/openai-realtime-api/src/index.ts` (+4/-4): Sets the default realtime model to `gpt-realtime-2.1-mini`. Updates the class example, the model-option documentation, and the constructor example. - `voice/openai-realtime-api/src/connection.integration.test.ts` (+24/-1): Adds a local WebSocket handshake test. The `setup` helper accepts an optional model and types the connection callback with the WebSocket and `IncomingMessage`. Parameterized tests check the model in the connection URL for two cases: no model configured (expects `gpt-realtime-2.1-mini`) and an explicit model (expects that model). - `voice/openai-realtime-api/README.md` (+1/-1): Usage example uses `gpt-realtime-2.1-mini`. - `docs/src/content/en/integrations/voice/openai.mdx` (+2/-2): Realtime usage example and constructor options use `gpt-realtime-2.1-mini`. - `.changeset/realtime-mini-default.md` (+5/-0): Patch changeset for `@mastra/voice-openai-realtime`. **Behavior** - Without a `model` option, the connection URL requests `gpt-realtime-2.1-mini`. - With a `model` option, the connection URL requests the configured model. - No exported or public declarations change. **Validation** The author reports these commands. This summary does not confirm their results: - `pnpm turbo build --filter="@mastra/voice-openai-realtime^..."` - `pnpm --dir voice/openai-realtime-api test` (70 tests) - `pnpm --dir voice/openai-realtime-api exec tsc --noEmit --project tsconfig.json` - `pnpm --dir voice/openai-realtime-api lint` - `pnpm --dir voice/openai-realtime-api build` **Scope limits** The linked issue also mentions future shutdowns for `whisper-1` and `tts-1`. This change does not alter those defaults. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
b75348adbd |
docs: redirect commonly hallucinated docs URLs to real pages (#30126) | ||
|
|
0fe65182d8 |
docs(evals): link datasets, experiments, and the eval loop from the Evals overview (#30124) | ||
|
|
064c1ff2e2 |
docs: redirect /docs/agents/mcp-guide to the MCP page (#30122) | ||
|
|
f5c7626fe7 |
docs(mcp): link runtime-tools example to durable agents and background tasks (#30120) | ||
|
|
4e028252d1 |
docs(sandbox): clarify that LocalSandbox workingDirectory doesn't copy the project (#30119) | ||
|
|
edb61ca939 |
docs(workspace): explain provider requirement when indexing supplied text (#30117) | ||
|
|
8e26648e8b |
docs(schedules): explain that workers must be running for schedules to fire (#30116) | ||
|
|
f3f304bc1f |
docs(mastracode): fix goal continuation, ResolutionPolicy, and mode default models (#30103)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> |
||
|
|
3ca0af7cf4 |
docs: show how to save audit records with agent tool hooks (#30106) | ||
|
|
aa49b049d0 |
feat(observability): order completed spans by duration (#30085)
Adds `durationMs` ascending/descending ordering to `querySpans()`, combined with existing duration filters and stable cursor pagination. Duration is the completed span’s elapsed time; zero is valid. Trace ordering and trace runtime semantics are unchanged. The server advertises `spanQueryDurationSort` and rejects unsupported stores before execution. A span-specific field list and default-off planner option protect old servers paired with newer Core. Updated adapters advertise support only when Core understands it. PostgreSQL and DuckDB reuse their numeric ordering paths; ClickHouse handles numeric cursor parameters and normalizes duration values returned as Int64 strings. Includes generated API types, documentation and package changesets. No schema migration. Implements the OSS portion of [OBS-899](https://linear.app/kepler-crm/issue/OBS-899). [OBS-904](https://linear.app/kepler-crm/issue/OBS-904) tracks Platform integration after merge and a snapshot from main. UI is outside this backend change. Validation: 134 Core, 112 server, 125 Client JS, 100 PostgreSQL, 94 DuckDB and 103 ClickHouse tests passed (one existing ClickHouse skip). Shared conformance exercises both directions, filters, zero durations and ties across page sizes. The new Core tests fail before the implementation; reverting the ClickHouse cursor fix makes both new pagination cases fail by skipping rows. Old-Core adapters omit the new feature; old stores receive a structured 501. Core/server/store typechecks, Core/server/SDK builds, changed-file lint/format and required docs checks passed. Vale reports six warnings in unchanged text. Local Node 23.11.0 is outside the supported 22/24 versions; CI must verify supported runtimes. A bounded local ClickHouse 26.6.8.7 experiment used 20,000 synthetic completed spans, the same duration filter and 50-row first/second pages in both directions. Duration ordering peaked at 3.43–3.67 MiB versus 3.42–3.66 MiB for timestamp ordering; both read 20,000 rows/1,488,890 bytes. Duration query CPU was 7–25 ms. These are single-run local measurements, not production capacity evidence; no ingestion or storage layout changed. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR lets users sort completed spans by how long they took. It keeps pagination stable and enables the feature only when Core and the storage adapter support it. ## Changes - Added ascending and descending `durationMs` ordering to `querySpans()`. - Added duration-aware cursor validation and stable pagination. - Added `spanQueryDurationSort` capability reporting. - Added HTTP 501 handling for unsupported stores. - Added compatibility gates for older Core versions. - Updated PostgreSQL, DuckDB, and ClickHouse adapters. - Converted ClickHouse duration values to numbers. - Added Core, server, adapter, and conformance tests. - Updated generated API types, documentation, and package changesets. - No schema migration was added. ## Validation - Reported passing tests: Core 134, server 112, Client JS 125, PostgreSQL 100, DuckDB 94, and ClickHouse 103. - One existing ClickHouse test remains skipped. - Reported typechecks, builds, lint, formatting, and documentation checks passed. - Vale reported six warnings in unchanged text. - CI verification on supported Node.js versions is not available. - Diff size: 28 files changed, with 220 additions and 8 deletions. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
b2e0e40b57 |
feat(cli): align score and feedback API commands (#30089)
Closes [OBS-794](https://linear.app/kepler-crm/issue/OBS-794). Adds `feedback create`, `list`, `get`, `replace`, and `review-status`, plus `aggregate`, `breakdown`, `timeseries`, and `percentiles` for both scores and feedback. Creates generate missing IDs and timestamps once and preserve them across bounded HTTP retries and credential fallback. Replacements require the original identity and timestamp; review-status updates preserve missing-record errors. Context-mode omission and feedback author fields are passed through without inferring values. List output preserves pagination and delta cursors, and write output retains the server's success and identity data. Score/feedback schemas are generated from the server routes and bundled for `--schema` without requiring a target schema endpoint. Most of the diff is that generated file. Includes help examples, CLI reference docs, and a minor `mastra` changeset. Validation: 221 CLI API tests, including 57 real-HTTP cases; 20 repeated timeout/credential-fallback runs; CLI typecheck; type-aware lint/precommit checks; docs check with Vale and the CI Vale configuration. Validated all 14 write/analytics help examples against the current server body schemas. Missing-anchor retries, transient failures, credential fallback, older success-only responses, unsupported endpoints, and API-prefix/auth headers are covered. The full `turbo build --filter mastra` stopped in the unchanged `@mastra/playground-ui` declaration step (`tsc found type errors`, with no underlying diagnostic emitted) before building the CLI. Local checks used Node 23.11.0, which is outside the repository's requested engine range. Live Platform writes and package publication/deployment were not tested. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR adds commands to create, review, list, and analyze scores and feedback. It also makes retries safer by preserving the same IDs, timestamps, and request data. ## Changes - Added feedback `create`, `list`, `get`, `replace`, and `review-status` commands. - Added `aggregate`, `breakdown`, `timeseries`, and `percentiles` for scores and feedback. - Added validation for write inputs and feedback replacement identity. - Added bounded retries for transient failures and credential fallback. - Preserved pagination cursors, response identity data, and feedback fields. - Bundled generated score and feedback schemas for offline `--schema` output. - Added unsupported-endpoint errors for HTTP 405 and 501 responses. - Updated documentation, help examples, and the `mastra` changeset. - Added HTTP-backed tests for commands, validation, retries, responses, and schemas. ## Validation - The author reports 221 CLI API tests, including 57 real-HTTP cases. - The author reports passing typecheck, lint, precommit, Vale, and documentation checks. - The build stopped in the unchanged `@mastra/playground-ui` declaration step before the CLI build. - Local checks used Node 23.11.0, outside the repository’s requested engine range. - Live Platform writes and package publication or deployment were not tested. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
b0ef22e7bf |
feat(schedules): Add bounded one-off schedules (#25131)
> Opened by @abhiaiyer91 Refs #24610 ## Summary Schedules can now fire once or stop after a given time, so you no longer need to pin a cron expression to a date and clean it up yourself. - **New `completed` status**: the scheduler and timing reconciliation set it when no automatic fires remain. It's written in the same atomic `nextFireAt` check-and-set used to claim a run, so a schedule still fires only once across instances. A cron with no future occurrence left also moves to `completed` instead of erroring. `pause`/`resume` on a completed schedule return 409. Changing `runAt`/`endAt` reactivates it only when the resulting timing can still fire. `list()` hides completed schedules unless you pass `status: 'completed'`. - **Declarative workflow schedules**: `createWorkflow({ schedule: { runAt } })` and `{ cron, endAt }` are supported. Past times are accepted so redeploys don't fail, and a completed schedule isn't re-armed unless its timing changes. - **Trigger kind**: one-off fires report `trigger.kind: 'once'`. - `run(id)` doesn't complete a one-off schedule. ## Surfaces - **Core**: types, validation, scheduler claim logic, create/update/pause/resume/list, declarative sync. - **Storage**: new nullable `run_at`/`end_at` columns for libsql, pg, mysql, mongodb, spanner, convex and in-memory. Existing columns are untouched: one-off schedules store `cron` as `''`. `updateScheduleNextFire` takes an optional `newStatus`. - **Server/client-js/CLI**: request bodies accept `runAt`/`endAt` (one-of rule checked in the schema). Responses include the new fields and `completed`. Route types and CLI route metadata regenerated. - **Studio**: shows the run time for one-off schedules, shows the `endAt` bound, adds a `completed` badge and hides pause/resume for completed schedules. - **Docs + changeset.** ## Not in this PR (remaining #24610 work) - ISO 8601 string inputs for `runAt`/`endAt` (numbers and `Date` are accepted today). - The template `schedule_once` tool. ## Test plan - [x] core: schedules, scheduler, cron, schedule-config and scheduler integration tests (260 passing), clean `tsc` - [x] Shared adapter suite gained tests for `runAt`/`endAt` round-trip and atomic status CAS. Passing on libsql, pg, mysql and mongodb (Docker), plus convex server tests. **Not run on Spanner (no emulator available); typecheck only.** - [x] server schedules handler tests (51 passing, including one-off/bounded creation and body validation) - [x] client-js and playground typecheck clean; playground schedules tests passing <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 Schedules can now run once at a chosen time or repeat until a chosen end time. They complete when their planned runs are over, and changing their timing can make them active again. ## Summary - Added `runAt` for one-off agent and workflow schedules. API-created schedules require a future `runAt`; declarative workflow schedules can register past times as `completed`. - Added `endAt` for cron schedules. A schedule becomes `completed` when its next run would occur after `endAt`, or when no future run remains. - Completed schedules cannot be paused or resumed. Timing changes can reactivate a completed schedule when a future run remains. `list()` hides completed schedules unless callers filter with `status: 'completed'`. - Resuming a paused one-off schedule after its `runAt` has passed allows it to fire on the next scheduler tick. Calling `run(id)` manually does not complete a one-off schedule. - Added the `once` trigger kind for scheduled one-off agent fires. Manual runs remain `manual`. - Declarative workflow schedules preserve completed status across redeploys when timing is unchanged. Timing changes can re-arm them. - Updated schedule APIs, storage adapters, Studio, and documentation. Storage persists `runAt` and `endAt` and supports atomic status updates. ## Checks Current-head CI, build, and test results: not available. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> Co-authored-by: NikAiyer <nick.aiyer@gmail.com> Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: Ehindero Israel <iehindero419@stu.ui.edu.ng> |
||
|
|
cb5fa0dffb |
docs: fix reference drift in Express adapter, generateLegacy, and observability pages (#29984) | ||
|
|
2053c881ed |
fix(observability): export feedback review-status updates (#30075)
HTTP feedback review-status changes persist locally but do not reach
exporters. This forwards successful updates to supporting exporters and
adds `observability.updateFeedbackReviewStatus({ feedbackId,
reviewStatus })` for independent SDK delivery. A missing or slow local
record does not block remote delivery; the HTTP route still requires an
existing local record, honors the configured resourceId, and returns its
updated value. Organization IDs remain metadata and do not scope this
PATCH route.
MastraPlatformExporter sends the existing review-status PATCH contract,
retries recognized missing-feedback and temporary lookup responses, and
tracks delivery through flush/shutdown. Replacement PUTs and review
PATCHes for the same feedback ID share one queue through retries,
including failure recovery. This orders requests from one exporter
instance; successful publication still does not guarantee that a
subsequent PATCH reads the latest queued PUT from Platform storage.
Storage exporters wait for earlier creates of that feedback to resolve
and persist before updating it, including buffered and in-flight writes.
Other exporters remain independent. Optional hooks let older exporters
skip the update safely; HTTP updates still work when observability lacks
the notification hook. This covers review status only, with no general
PATCH or UI changes.
Fixes #24054, completing its remaining review-status exporter gap after
the create/replacement work. Part of OBS-785. Platform delivery requires
the matching endpoint from merged mastra-ai/platform#4651 to be
deployed; the Platform UI rollout remains separate.
Validation: the HTTP export regressions failed before the fix and pass
afterward. Shared HTTP suites pass in Hono, Express, Fastify, NestJS and
Koa (92 tests each); exporter HTTP tests (163 in the latest run) and
neighboring observability tests (234), and server handler tests (167)
pass. The retry-ordering, buffered-create, and inherited-hook
regressions failed before their fixes. Timing-sensitive ordering tests
passed 20 repeated runs, including PUT/PATCH in both directions with
flush/shutdown and independent IDs. Relevant builds, client-js build,
typed lint, formatting and docs checks pass. Route metadata regeneration
produces no diff. Local validation used Node 23.11.0, outside the
repository's supported engine range. Docs checks and CI-equivalent Vale
lint pass with Vale 3.25.1 installed.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR sends feedback review-status changes to observability exporters,
not only local storage. It also adds an SDK method for sending these
updates directly.
## Summary
- Added `observability.updateFeedbackReviewStatus({ feedbackId,
reviewStatus })`.
- Added the `feedback_review_status` event and exporter hooks.
- Updated the HTTP route to validate local feedback and `resourceId`,
update local storage, return the updated record, and notify exporters.
- Added Platform `PATCH` delivery with retries for recognized
missing-feedback and temporary lookup responses.
- Serialized updates for the same feedback ID while keeping different
IDs independent.
- Allowed remote delivery when local feedback is missing or local
storage lacks review-status support.
- Preserved compatibility with exporters that do not implement the new
hook.
- Tracked pending updates through `flush()` and shutdown.
- Added documentation, changesets, and regression tests.
- Scope remains limited to review-status updates. No general `PATCH`
behavior or UI changes.
## Validation
- 21 files changed: 752 additions and 50 deletions.
- Reported HTTP suites passed for Hono, Express, Fastify, NestJS, and
Koa, with 92 tests per suite.
- Reported exporter HTTP tests, neighboring observability tests, and
server handler tests passed.
- Reported builds, client-js build, typed lint, formatting,
documentation checks, and route metadata checks passed.
- Vale validation used version 3.25.1.
- Validation used Node 23.11.0, outside the repository’s supported
engine range.
- Platform delivery requires deployment of the matching endpoint from
`mastra-ai/platform#4651`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
|
||
|
|
bb0e97e2aa |
feat(connect): use connected tools through Code Mode (#29583)
This adds `codeMode()` to the connect `tools()` resolver, so an agent
can call its connected tools from one TypeScript program instead of one
tool call per step. It's handy when a task fans out across many calls or
providers.
```ts
import { tools } from '@mastra/connect'
import { LocalSandbox } from '@mastra/core/workspace'
const code = tools().codeMode({ sandbox: new LocalSandbox() })
const agent = new Agent({
instructions: async ctx => ['You are helpful.', await code.instructions(ctx)],
tools: code.tools,
// ...
})
```
`createCodeMode()` takes a fixed tool record, but connect tools change
with each request, so `codeMode()` returns per-request `tools` and
`instructions` functions. Both use the same resolution within a request,
so the instructions never describe a function the program can't call.
Tools that need approval, and `request_connection`, stay regular agent
tools so the run can still pause for them. When nothing is connected you
get just the direct tools and an empty instructions string.
Declaring every connected function in the instructions costs about 4k
tokens per provider (over 150k for the whole catalog) on every turn. So
when the declarations would pass about 10k tokens, `codeMode()` lists
only the function names and gives the agent a `search_functions` tool.
The agent searches by task or by exact name, gets the TypeScript
declarations back, then writes the program. Every function stays
callable from the program. `toolSearch: true` or `false` picks the mode
explicitly.
Tested against a real Agent, the real Linear tools and a real sandbox
process, with only the model and the platform HTTP faked (498/498
connect tests). I also ran it live with gpt-4o-mini against a real
project: the model wrote one program that called the connected Word,
Excel and PowerPoint accounts through the platform proxy. With tool
search forced on, gpt-5-mini got a 789-token instruction block listing
45 names, searched for the Word and Excel list functions and the drive
lookup, then wrote one program that read the real OneDrive. Docs are in
the connect `tools()` reference, with a pointer from the Code Mode
guide.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Agents can use connected tools in one TypeScript program instead of
calling each tool separately. Agents can look up tool details when
needed, while approval-required tools remain directly controlled by the
agent.
## Summary
- Added `codeMode(options)` to static, dynamic, and `.with()` Connect
tool resolvers.
- Returned `tools` and `instructions` functions resolve the same
connections for each request.
- Shared builds remain cached for up to 30 seconds for the same request
context.
- Approval-required and suspended tools, including `request_connection`,
remain direct agent tools.
- Added `search_functions` for on-demand function declarations.
- Tool search activates automatically above about 10,000 declaration
tokens. `toolSearch` can force it on or off.
- Added documentation, a changeset, and integration tests.
- Test results: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
|
||
|
|
c860b9bb43 |
feat(observability): support OSS feedback replacement (OBS-887) (#30059)
Implements [OBS-887](https://linear.app/kepler-crm/issue/OBS-887/add-oss-feedback-replacement-and-export). Add OSS `PUT /api/observability/feedback/:feedbackId` with the existing wrapped client request. Replacements retain the original feedback ID, trace ID, timestamp, and tenant; omitted optional fields are cleared. A full replacement can create a missing record. OSS persists locally before responding, then independently notifies supporting exporters. Resolve mode still requires the local anchor. The SDK also exposes optional `replaceFeedback()` for independent exporter delivery without a producer-side storage lookup. Replacement events use a separate optional exporter hook. `MastraPlatformExporter` sends PUT with stable identity across bounded anchor retries, and flush/shutdown drain deliveries. Older exporters skip replacements rather than replaying them as creates. Unsupported storage/package combinations return 501 or skip unavailable export support. No UI changes; review-status PATCH propagation remains tracked in OBS-785. In-memory, PostgreSQL vNext, DuckDB, and ClickHouse vNext support replacement. In-memory, PostgreSQL, and DuckDB enforce replacement identity at the write. PostgreSQL coordinates writes by feedback ID, including duplicates submitted with a different timestamp. Duplicate HTTP creates return the stored identity and timestamp and re-notify exporters with accepted values. Tenant mismatches remain hidden, and an omitted SDK replacement author stays null. HTTP/exporter creates use `onConflict: 'ignore'` so a delayed original create doesn't undo an edit; direct storage calls keep their legacy upsert default. **ClickHouse requires no migration:** it uses the existing schema and read-before-insert protection. Sequential delayed creates are covered, but overlapping writes from separate processes can race; this is not a globally ordered or exactly-once protocol. Latest review fixes: DuckDB's lazy facade delegates replacement to its guarded writer; concurrent coverage runs 20 overlapping request pairs per identity variant. Direct storage replacements normalize an omitted author to null. PostgreSQL single-feedback reads use the primary for read-after-write consistency, while list/aggregate reads retain the configured read client. Batch advisory locks use one ordered query with unchanged lock keys. Validation: the stronger DuckDB regression failed on all four identity variants before the facade fix. Afterward, the entire DuckDB package passed 718 tests across 21 files in three consecutive runs. PostgreSQL passed 57 feedback tests, including a real stale read snapshot and overlapping reversed 1,000-ID batches. Shared replacement tests passed on in-memory (12), and the new author regression passed on ClickHouse without a migration. Core/storage builds and declarations, typed lint, and formatting passed. Earlier HTTP (85 cases on each of four adapters), generic Hono routes (2,848), server/system, exporter, and docs checks remain recorded in the PR history. Local tests use Node 23.11.0; CI validates the supported runtime. The unrelated Traces UI fade assertion failure was fixed in https://github.com/mastra-ai/mastra/pull/30068; this branch includes that fix from main. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR lets users replace feedback without changing its identity. It stores the replacement locally and sends it to supported exporters without allowing delayed creates to overwrite it. ## Changes - Added `PUT /api/observability/feedback/:feedbackId`. - Preserved the feedback ID, trace ID, timestamp, and tenant. - Cleared omitted optional fields. - Added capability detection and `501` responses for unsupported storage. - Added replacement event types, SDK support, client types, route metadata, and documentation. - Added replacement delivery, stable retries, flush handling, and shutdown draining for `MastraPlatformExporter`. - Added replacement support for in-memory, PostgreSQL vNext, DuckDB, and ClickHouse vNext. - Added `onConflict: 'ignore'` for HTTP and exporter creates. Direct storage calls retain their upsert default. - Older exporters skip replacements instead of replaying them as creates. - Added ClickHouse support without a migration. Concurrent writes from separate processes can still race. - No UI changes were included. ## Validation The author reports passing the HTTP route and contract suites, feedback storage suites, partition and SQL tests, server and system tests, record-builder tests, build, typecheck, lint, and documentation checks. For the current head, the available CI result is `2027dev Evals: skipped`. Other listed CI checks target different commits or remain in progress. Current-head CI results are otherwise not available. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
166ad37deb |
fix(observability): deliver feedback and scores independently to exporters (#30052)
Feedback and scores submitted with only a trace/span ID can be dropped
before reaching remote exporters because the SDK first looks in local
storage. For example, `addFeedback({ traceId, feedback })` cannot
currently reach Platform when that trace exists only there. This change
dispatches to every supporting exporter immediately and moves local
lookup/retries into MastraStorageExporter and the deprecated
DefaultExporter. Each storage exporter enriches its own copy while
preserving the original ID and timestamp.
OSS HTTP creates keep their existing local persistence and response
contract, then notify exporters without writing through the storage
exporter again. Supplied context, including an empty object, stays
supplied. Exported feedback preserves the author and review status,
including an explicitly null author. Pending storage lookups and custom
exporter deliveries are included in flush/shutdown. HTTP creates return
after local persistence and enqueue exporter delivery without waiting
for custom handlers to finish. Studio routing is unchanged: writes
target the backend serving reads.
Local context resolution requires the target span’s actual ancestor
root. Missing parents are retried, then logged and skipped locally; we
intentionally do not borrow another root’s tags or store incomplete root
context. Other exporters still receive the record independently.
Transient storage-read errors use the same bounded retry window and
report the final read error when exhausted.
Validated after review with 316 exporter/bus/recorded-span tests and 69
HTTP contract tests each on Hono, Fastify, and Koa (523 tests). The four
custom-exporter timing cases also passed 20 repeated runs. The
read-error and HTTP-latency regressions failed before their fixes, and
temporarily allowing the orphan fallback failed the new root-context
regression. Six older mocked forwarding/race tests are replaced by real
storage and HTTP coverage. Package builds, observability production and
adapter-suite typechecks, changed-file lint, and docs checks pass;
generated route types and CLI metadata are unchanged.
Express and NestJS tests hit a JSON body-parser failure before our
handlers. Standalone Express with no Mastra code reproduces `getBody is
not a function` under the local Node 23.11.0 runtime. The standalone
observability typecheck also retains four existing errors in
`workflow-control-flow-suite.ts`. These are not fixed here.
Fixes [OBS-886](https://linear.app/kepler-crm/issue/OBS-886) and
addresses the create-delivery portion of
[#24054](https://github.com/mastra-ai/mastra/issues/24054). Feedback
replacement remains in
[OBS-887](https://linear.app/kepler-crm/issue/OBS-887), and
review-status PATCH propagation remains in
[OBS-785](https://linear.app/kepler-crm/issue/OBS-785).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR sends feedback and score records to each exporter independently.
Missing local traces no longer prevent remote delivery, and HTTP-created
records keep their original data.
## Summary
- Added exporter-specific event routing.
- Moved trace and span resolution into `MastraStorageExporter` and
`DefaultExporter`.
- Added bounded retries for storage lookups.
- Added pending annotation delivery before `flush()` and shutdown.
- Added asynchronous exporter notifications after successful HTTP
persistence.
- Prevented duplicate storage writes for HTTP-created records.
- Preserved IDs, timestamps, context, authors, anonymous feedback,
metadata, and review status.
- Added nullable `feedbackUserId` and `reviewStatus` support.
- Added SDK and HTTP adapter integration tests.
- Updated documentation, package metadata, and changesets.
**Diff:** 30 files changed; 954 additions and 483 deletions.
## Validation
- Reported: 503 focused tests passed, including 65 HTTP contract tests
for each of Hono, Fastify, and Koa.
- Reported: builds, changed-file lint, and documentation checks passed.
- Express and NestJS tests fail during JSON body parsing with `getBody
is not a function`.
- Standalone observability typecheck retains four existing errors.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
|
||
|
|
8ab6015fb4 |
fix(client-js): support accepted observability deletion responses (#30051)
The JS client accepts HTTP 202 deletion responses at runtime, but its
types only describe OSS success responses. Include `{ accepted: true }`
in the return types of `deleteTraces`, `deleteScores`, and
`deleteFeedback`, with docs and a patch changeset explaining
asynchronous acceptance. Export the three response types from the public
client entry point so downstream packages can emit portable
declarations. OSS server/storage behavior and generated route contracts
are unchanged; Platform endpoints and rollout remain separate work.
Callers that previously read `result.success` directly need to narrow
the response:
```ts
const result = await client.deleteFeedback({ feedbackIds: ['feedback-1'] });
if ('accepted' in result) {
console.log('Deletion requested');
} else {
console.log(result.success);
}
```
Verified 137 focused runtime tests, the new type regression (fails
before the fix), TypeScript checks, the client build, the downstream
React SDK build (including declarations), package lint, formatting, and
documentation checks. The HTTP suite replaces the mocked deletion tests
and covers 200/202 bodies, POST/DELETE JSON preservation, and 400/500
failures. Docs checks have zero errors and three warnings on unchanged
text. No deployed Platform end-to-end flow was tested.
Fixes OBS-889.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Deletion requests can now mean “cleanup accepted and queued” instead of
“cleanup finished.” The JavaScript client now supports both responses
and documents how to handle them safely.
## Changes
- Added `{ accepted: true }` to the response types for `deleteTraces`,
`deleteScores`, and `deleteFeedback`.
- Exported these response types from the public client entry point.
- Added HTTP tests for `200`, `202`, `400`, and `500` responses,
including request details and response-body preservation.
- Added TypeScript regression tests for both client entry points and
response narrowing with `'accepted' in result`.
- Updated client and observability documentation to explain asynchronous
Platform cleanup.
- Added a patch changeset for `@mastra/client-js`.
- Replaced the previous deletion tests with shared deletion coverage.
- No server or storage implementation changes were made.
## Validation
- Test and build execution results: not available.
- The diff includes runtime and type-test coverage for the updated
behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
|
||
|
|
447367781c |
feat(observability): export feedback and scores with Platform context resolution (#30048)
Feedback and score events without correlation context currently go through collector batching even when Platform needs to resolve their trace/span. Send those records immediately to the wrapped observability POST endpoints; keep supplied-context records on the existing collector batch path. Retry recognized missing-anchor 404s and lookup-unavailable 503s with stable IDs, timestamps, and payloads, bounded by six attempts and 30 seconds. Honor Retry-After within that deadline, and drain pending deliveries during flush/shutdown. Collector quota pauses do not suppress these requests. Other failures are logged and dropped; any 2xx completes delivery without polling for persistence. This only handles events that reach the exporter. Producer-side local lookups, HTTP-to-exporter notifications, and PUT/PATCH propagation remain outside this change. Includes reference docs and a minor @mastra/observability changeset with a usage example. Validated with 562 exporter tests, final retry/deadline checks, package build, targeted type-aware lint, and docs checks (Vale unavailable). The routing regressions fail against the original exporter. Package-wide tsc reports the same four workflow-control-flow-suite errors with and without this implementation. Fixes [OBS-825](https://linear.app/kepler-crm/issue/OBS-825). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR sends feedback and score events to Platform when they do not include correlation context. It retries temporary lookup failures and waits for delivery during `flush()` and shutdown. ## Changes - Added direct delivery for feedback and score records with `correlationContext == null`. - Kept records with supplied context, including `{}`, on the collector batch path. - Required a non-blank `traceId` for direct delivery. - Added project-aware endpoints, authorization, stable payload snapshots, and project headers. - Added up to six total attempts within 30 seconds for recognized `404` and `503` anchor lookup errors. - Added exponential backoff and `Retry-After` support. - Dropped non-retryable failures, network failures, invalid records, and exhausted deliveries with warnings. - Waited for direct deliveries during `flush()` and `shutdown()`. - Kept direct deliveries active during collector quota pauses. - Added HTTP coverage, reference documentation, and a minor-release changeset. ## Scope The change applies to events received by `MastraPlatformExporter`. It does not change producer-side context lookup, exporter notifications, or `PUT`/`PATCH` propagation. ## Validation Completed CI, build, and test results are not available. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
9ee332c1fd |
feat(ui): rounded squircle favicon for Studio, Factory and docs (#30040)
The tab icon gets rounded corners, matching the rounded style used everywhere else in the UI. Today's tile has a 5% corner radius, which reads as a plain square at 16px. The new tile is a squircle (superellipse, n=7), the smooth corner shape app icons use. The logo is at 80% of the tile width and centered, so it has a little room from the corners. ## Before / After | Before | After | | --- | --- | | <img src="https://github.com/user-attachments/assets/de26b6ac-83db-4212-9a46-a73b36daa714" width="400" alt="Before"> | <img src="https://github.com/user-attachments/assets/d1f885ba-c647-4fa6-9a7d-58e7b72dcf02" width="400" alt="After"> | ## What changed - Studio (`mastra-dark-tile.svg`, green dev variant), Factory (`mastra.svg`, `mastra-dev.svg` and the four session status icons) and the docs `favicon.ico` all come from the same source, so they stay identical. - Factory's status dot still sits on the logo's bottom-left dot. - `mastra studio` now serves `/mastra-dark-tile.svg` as a file. It still checked for the old `/mastra.svg` name, so the tab got the page HTML instead of the icon. ## Scope - Factory's PWA and apple-touch PNGs stay as they are: the OS masks those itself, so a rounded tile inside them would look double-rounded. - Platform and mastra.ai get the same icon in their own PRs. ## Testing 1. Run Studio or Factory: the tab shows the rounded tile (green logo in dev). 2. Factory: open a session, and the colored status dot shows on the same rounded tile. 3. Docs: the tab shows the rounded tile from `favicon.ico`. 4. Run `mastra studio`: the tab shows the rounded tile. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## ELI5 This PR makes the Mastra favicon more rounded across Studio, Factory, and the docs. It also makes Studio serve the correct icon file so browsers display it. ## Changes - Updated Studio, Factory, and Factory session-status SVGs with the rounded tile design. - Replaced the docs `favicon.ico`. - Updated Studio asset handling to serve `/mastra-dark-tile.svg`, including nested paths. - Added a test for serving the Studio favicon instead of the SPA HTML. - Added patch changesets for `mastra` and `@mastra/factory`. ## Validation - Test results: not available. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
|
092dd3c96d |
Add Docker Cloud Sandboxes microVM provider to @mastra/docker (#29356) | ||
|
|
59a60e42d5 |
feat(core): export REPROCESS_PART_KEY so custom output processors can emit two chunks (#29939)
## Description
`processOutputStream` returns one chunk. Core already lets an output
processor emit a second chunk for the same input: the processor stashes
it on `state` under `REPROCESS_PART_KEY`, and the runner emits it right
after the returned chunk, through the processors again.
`BatchPartsProcessor`, the PII detector and the regex filter all use
this.
The key was not exported, so a processor outside core had to copy its
internal string (`'__mastraReprocessPart'`). A rename in core would then
break that processor with no type error. This PR exports the key from
`@mastra/core/processors`.
```ts
import { REPROCESS_PART_KEY } from '@mastra/core/processors';
async processOutputStream({ part, state }) {
if (part.type !== 'text-end' || state.signed) return part;
state.signed = true;
state[REPROCESS_PART_KEY] = part; // emitted after the delta below
return { ...part, type: 'text-delta', payload: { id: part.payload.id, text: '\n\nCheers!' } };
}
```
The first user is `@mastra/json-render` (#29914), which needs it to
release text it held back at the end of a reply before the text block
closes.
No runtime behavior changes; this only exports an existing constant.
## Docs
The processor interface reference gets an "Emitting a second chunk"
section under `processOutputStream`, with the example above. It says the
stashed chunk goes through the processor that stashed it again, so that
processor must pass it through on the second pass.
## Type of change
- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update
## Test plan
- New `src/processors/reprocess-part-key.test.ts` runs the docs example
in a real `Agent` with memory. It checks the streamed text and that
`text-end` comes after the added delta, that a processor after the
stashing one also gets the stashed part, and the saved message text.
- Mutation check: removing the stash line makes the test fail
(`text-end` goes missing).
- oxlint and prettier clean; docs `pnpm check` has 0 errors.
- `tsc --noEmit` in core reports one error, in
`observability/mastra/src/exporters/storage-platform-policy.ts`. That
error is also on clean `main` and is not caused by this PR.
## Checklist
- [x] Tests added
- [x] Docs updated
- [x] Changeset added
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
A custom processor can now use a public key to set aside a chunk and
have Mastra send it after another chunk. This lets processors add or
release text without copying an internal string.
## Changes
- Export `REPROCESS_PART_KEY` from `@mastra/core/processors`.
- Document how to stash a chunk and explain that it passes through the
output processors again.
- Add a test that checks chunk order, processing by a following
processor, and saved assistant text.
- Add a patch changeset for `@mastra/core`.
## Checks
Test and CI results: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
|
||
|
|
d41d7ac33d |
feat(mastracode): approving a plan starts it as a goal (#28037) | ||
|
|
2d16c84823 |
feat(factory): Factory-wide sandbox environment variables (#29923)
Factory members can now add environment variables for every sandbox in a
Factory, under Settings › Manage Factory › Environment variables. Each
variable is marked Build, Runtime, or Both.
Runtime variables reach every command in the Factory's sandboxes.
Adding, editing or deleting one takes effect on the next command in a
sandbox that's already running, with no restart (processes already
running keep their old env). Build variables reach template builds and
Factory's setup commands, never runtime commands, and editing one makes
the next build rebuild the template.
Values are encrypted at rest, never returned by the API or shown in the
UI after saving, and never put into template names, identity, or images.
Saving is blocked when sign-in is on but no credential encryption key is
configured.
To make builds work, `FactorySandboxContext` gets two optional fields.
Providers pass `buildEnv` only to a build-only mechanism and put
`buildEnvRevision` (a random id, never derived from values) in template
identity:
```ts
const { buildEnv, buildEnvRevision, ...rest } = ctx;
return createRepoTemplate({ ...rest, buildEnvRevision });
```
The platform and E2B workspace packages pass Build variables to template
builds. Docker keeps them out of the image and its identity, and doesn't
apply them to template builds yet. The routes are also available from
the CLI as `mastra api factory project environment variables
list|set|update|delete`.
Tested with unit tests on a real local sandbox, route tests that check
no response ever contains a value, and UI tests. I also ran it end to
end against a Platform sandbox: a Runtime variable's new value showed up
after an edit and was gone after a delete, and a Build variable was seen
by setup but not at runtime, with an edit producing a new build.
Part of FACT-554
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Factory admins can save environment variables for a project and choose
whether each one is used to build sandboxes, run commands, or both.
Factory protects the values and applies changes to later commands or
relevant builds.
## Summary
- Added encrypted, project-scoped storage and authenticated API routes
to list, set, update, and delete sandbox environment variables.
Responses include metadata, not values. When sign-in is enabled without
a credential encryption key, writes are blocked.
- Added a Factory settings interface and CLI commands to manage
variables with Build, Runtime, or Both scopes.
- Runtime variable changes refresh the environment before later
commands. Build variables are available to build contexts and setup
commands. Build-variable changes update a revision used by supported
providers for template identity.
- Reads are served from memory per server: the revision and decrypted
values are reused until a variable changes. A write clears this server's
entry and is announced on Factory's event bus so other servers drop
theirs; a cached read is re-checked after a minute with a cross-process
bus, or after a second without one.
- Added optional `buildEnv` and `buildEnvRevision` fields to
`FactorySandboxContext`. Platform and E2B pass Build variables to
template builds. Docker excludes these fields from template input and
identity; Docker template builds do not receive the variables.
- Added documentation and tests for storage, API routes, settings, CLI,
sandbox behavior, and provider handling.
**Diff size:** 54 files changed; 3,241 lines added and 50 removed.
<!-- 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>
|
||
|
|
c3ef10ee30 |
fix(core,mcp): warn when same-named MCP tools replace each other (#29415)
## Summary
When two MCP servers expose a tool with the same name and you pass
`toolsets: await mcp.listToolsets()` to an agent, the agent flattens
toolsets by tool name, so only the later server's tool reaches the model
and nothing is logged. `listTools()` has a smaller variant of the same
problem: server and tool names can both contain `_`, so `local` +
`x_status` and `local_x` + `status` both become `local_x_status`, and
one tool is dropped. This PR makes both cases log a warning, without
changing which tool wins, and fixes the `listToolsets()` reference,
which said its keys were namespaced.
```diff
Agent.listToolsets (packages/core/src/agent/agent.ts)
for each toolset, for each tool
+ if an earlier toolset already used this tool name
+ logger.warn(tool, [earlier toolset, this toolset])
toolsForRequest[toolName] = tool # last still wins
MCPClient.listToolsWithErrors / toolsFromDefinitions (packages/mcp/src/client/configuration.ts)
- tools[`${server}_${tool}`] = tool
+ setNamespacedTool(...) # same key, warns when a different pair already took it
```
Docs: the `listToolsets()` reference now says tools keep their raw
names, explains what happens on a collision, and shows `toolsets: { mcp:
await mcp.listTools() }` as a way to keep both tools at request time.
The `listTools()` reference describes the `_` key collision. The "Static
and runtime tools" table in the MCP guide gets a "Tool names" row.
## Evidence
New tests:
`packages/core/src/agent/__tests__/toolset-name-collisions.test.ts`
(real `Agent`, `stream` and `generate`, mock model, checks which tools
reach the model) and
`packages/mcp/src/client/tool-name-collisions.test.ts` (real MCP servers
over HTTP on 127.0.0.1, real `MCPClient`). Only the logger's `warn` is
spied on.
- **Before** (main's `agent.ts` and `configuration.ts` swapped in, same
tests):
```
× warns, naming both toolsets, when two toolsets expose `search`
(stream)
× warns, naming both toolsets, when two toolsets expose `search`
(generate)
Tests 2 failed | 1 passed (3)
× warns, naming both servers and tools, when `local`/`x_status` and
`local_x`/`status` collide
× warns the same way when rebuilding a cached catalog with
toolsFromDefinitions()
Tests 2 failed | 1 passed (3)
```
**After:** `Tests 3 passed (3)` in each file. Each test also asserts
that the winning tool is the same as on main (the later toolset or
server), and that tools with different names produce no warning.
What the warnings look like (captured from a real run):
```
[AGENT] Tool "search" from toolset "tickets" replaces the tool with the same name from toolset "docs", so the "docs" tool is not used. Give the tools distinct names to keep both. {
agent: 'Support Agent', tool: 'search', toolsets: [ 'docs', 'tickets' ], runId: '...'
}
[LLM] MCP tool key "local_x_status" from server "local_x" (tool "status") replaces the tool from server "local" (tool "x_status"), which produces the same key. Only the tool from "local_x" is kept. Rename one of the servers in `servers` to keep both. {
key: 'local_x_status', replaced: { serverName: 'local', toolName: 'x_status' }, replacedBy: { serverName: 'local_x', toolName: 'status' }
}
```
I also ran the docs workaround against two real MCP servers that both
expose `search`: with `toolsets: { mcp: await mcp.listTools() }` the
model received `docs_search` and `tickets_search`, and the snippet
typechecks.
Other checks run: existing `tools.test.ts`, `tool-handling.test.ts` and
`mcp-instructions.test.ts` (core), plus `configuration.test.ts` and
`discovery-settled.test.ts` (mcp), all pass. `tsc --noEmit` is clean for
core and for the touched mcp files. `oxlint` and `oxfmt` pass on the
touched files, and remark, oxfmt-mdx and Vale (error level) pass on both
docs pages. I took no docs screenshots: the change is two paragraphs, a
code block and one table row.
## Merge Danger
**Door:** two-way. The change only adds `logger.warn` calls and docs
text. No tool names, keys or winners change.
**Blast radius:** agents called with `toolsets` whose tool names
collide, and `MCPClient.listTools()` / `toolsFromDefinitions()` with
colliding `server_tool` keys. Those users now see one warning per
request (agent) or per discovery call (MCP client). Everyone else sees
no change.
Closes #29360
## Follow-ups
- Namespacing `listToolsets()` keys (the issue's first suggested fix)
would change the tool names the model sees, so it needs a maintainer
decision and is left out here.
- A toolset tool that replaces one of the agent's own `tools`, or a
`clientTools` entry that replaces a toolset tool, is still silent. That
is a different and possibly intentional override path, so this PR
doesn't warn on it.
- `mastra-mcp` typegen builds the same `${server}_${tool}` keys, so the
same `_` collision can produce a duplicate key in the generated types.
## Council review
| Round | Sol (GPT-6.1 Sol) | Opus (Claude Opus 5.5) | Grok 4.7 |
|---|---|---|---|
| 1 | Correctness 10, Tests 9, Scope 10, Code quality 10 | not run
(Sol-only round) | empty seat |
| 2 | 10 / 9 / 10 / 9 | 9 / 9 / 9 / 8 | empty seat |
| 3 | 10 / 9 / 10 / 9 | 9 / 9 / 10 / 9 | empty seat |
| 4 | 10 / 9 / 10 / 10 | 9 / 9 / 9 / 9 | empty seat |
Created with Claude Opus 5.5 in T3 Code.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
When tools from different servers have the same name, one can replace
another without notice. This change adds warnings when that happens and
updates the documentation, while keeping the existing rule that the
later tool wins.
## Changes
- Warn when an agent combines toolsets that contain the same raw tool
name.
- Warn when `listTools()` or `toolsFromDefinitions()` produce the same
`serverName_toolName` key for different server and tool pairs.
- Update the MCP documentation to explain raw tool names, collision
behavior, and how `listTools()` keeps server-prefixed names.
- Add tests for collisions, which tool remains, and distinct names.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
22b24cc40a |
fix(core): apply semanticRecall.filter during agent runs (#29418)
## Description
`semanticRecall.filter` worked in `Memory.recall()` but not during
`agent.generate()` or `agent.stream()`. During an agent run, recall
happens in the `SemanticRecall` processor, which never read `filter` and
queried the vector store with the scope filter only. So messages from
threads that didn't match the filter ended up in the prompt.
This PR changes
`packages/core/src/processors/memory/semantic-recall.ts`:
```diff
query filter
- scopeFilter
+ filter ? { $and: [scopeFilter, filter] } : scopeFilter // same as Memory.recall()
embedding metadata written during agent runs
- { message_id, thread_id, resource_id, ... }
+ { ...threadMetadata (only when filter is set), message_id, thread_id, resource_id, ... }
```
- The filter applies to both query paths: client-side embedder and
self-embedding stores.
- Embeddings written during agent runs had no thread metadata, so even
with the query fixed, a filter like `{ mode: { $eq: 'work' } }` could
never match messages that agents saved. When a filter is set, the
processor now reads the thread from storage and stores its metadata on
the embedding, as `Memory.saveMessages()` already does. It reads from
storage because durable and recovered runs put only the thread id in the
memory context.
- Without a filter, nothing about writes changes. Some vector stores
reject nested metadata values and this processor only logs a failed
upsert, so the metadata is written only when a filter needs it.
- Docs: added `filter` to the processor reference and a note on the
semantic recall page that messages agents saved before a filter was set
don't match it until they're saved or indexed again.
## Related issue(s)
Closes #29352
## Type of change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
## Evidence
Before = `semantic-recall.ts` from `origin/main`, with the same tests.
After = this branch.
- **Core, real Agent + MockMemory + in-memory vector store that applies
filters**
(`packages/core/src/processors/memory/semantic-recall-filter.test.ts`,
new): generate and stream, filter vs no filter, self-embedding store,
thread scope, durable-shaped context (`thread: { id }` only), thread
metadata written only with a filter.
**Before:** `Tests 7 failed | 2 passed (9)` (the two no-filter cases
pass on both).
**After:** `Tests 9 passed (9)`.
- **Memory integration, real `Memory` + LibSQL store and vector +
Agent**
(`packages/memory/integration-tests/src/semantic-recall-metadata-filter.test.ts`):
generate and stream; messages saved with `saveMessages()`, by earlier
agent runs, and in a thread the run created with metadata. Also checks
`Memory.recall()` agrees with the agent run.
**Before:** `Tests 6 failed | 2 passed (8)` (the two existing `recall()`
cases pass on both).
**After:** `Tests 8 passed (8)`.
- **The issue's own repro script** (LibSQL, mock embedder and model),
run against local builds:
**Before:** `agent prompt contains personal message: true`
**After:** `agent prompt contains personal message: false`
- Neighbouring core suites (`semantic-recall.test.ts`,
`processor-caching.test.ts`, `memory-config.test.ts`,
`embedding-dimension.test.ts`): 69/69 pass. `@mastra/core` typecheck
passes; oxlint, oxfmt and lint-staged are clean on the changed files.
Not tested: a real DurableAgent run end to end. The durable context
shape is covered by calling the Memory-built processor with `thread: {
id }` only, as `durable-agent.ts` and `finalize-run.ts` set it.
## Merge Danger
**Door:** two-way. A revert restores the old behavior. Embeddings
already written with thread metadata stay in the vector store but are
harmless extra fields.
**Blast radius:** agents with `semanticRecall.filter` configured. They
now recall fewer messages (only matching threads), which is the
documented behavior. Messages saved by older versions have no thread
metadata, so they won't match a filter until re-saved or re-indexed; the
changeset and docs say so. Users without a filter see no change in
queries.
**After merging main (#29826):** main's shared embedding helper now
always stores thread metadata on agent-run embeddings, so this PR no
longer adds its own filter-only metadata read; docs, changeset and the
unit test were updated to match.
**Cloudflare Vectorize (`@mastra/vectorize`):** the scope and user
filter are combined as `{ $and: [...] }` (the same shape
`Memory.recall()` already sends on main), which the Vectorize translator
rejected, so recall with a filter returned nothing there. The translator
now merges a filter that is exactly `{ $and: [...] }` into one object.
Several conditions on one field merge only as one lower plus one upper
bound; other same-field combinations and non-object clauses throw. Not
run against a live Vectorize index; checked against Cloudflare's
metadata-filtering docs and 38 translator tests (Sol reviewed 3 rounds).
## Council review
Rounds: 4
| Seat | Round 1 | Round 2 | Round 3 | Round 4 |
| --- | --- | --- | --- | --- |
| Claude Opus 5.5 | not run | not run | 8.5/10 | 9/10 |
| GPT-6.1 Sol | 9/10 (Tests 8, Code quality 8) | 9.6/10 | 9.5/10 |
9.5/10 |
| Grok 4.7 | empty seat | empty seat | empty seat | empty seat |
Created with Claude Opus 5.5 in T3 Code.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Agents now use the configured metadata filter when they search for
relevant messages. This keeps messages from unrelated threads out of the
agent’s prompt. Cloudflare Vectorize can also process the combined
filters used for these searches.
## Changes
- `SemanticRecall` combines the configured `VectorFilter` with the
thread or resource scope filter using `$and`.
- When a filter is configured, the processor reads thread metadata from
storage and writes it to message embeddings. Older embeddings may need
to be saved or indexed again.
- The Vectorize filter translator merges supported top-level `$and`
clauses, including repeated conditions with the same value. It rejects
unsupported combinations on the same field.
- Updated documentation and added tests for `generate()`, `stream()`,
self-embedding queries, and Vectorize filter translation.
## Verification
- Reported: 9/9 core filter tests, 8/8 integration tests, 69/69
neighboring core tests, 38 Vectorize translator tests, and the
`@mastra/core` typecheck passed.
- A real DurableAgent run was not tested end to end. A core test covers
a processor request context that contains only a thread ID.
- Live Cloudflare Vectorize testing: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
d8edfdfef6 |
docs(rag): document that rerank weights must be between 0 and 1 (#29977)
Co-authored-by: sdivyanshu90 <97019230+sdivyanshu90@users.noreply.github.com> |
||
|
|
c34ff7e927 |
docs(models): classify Requesty as a gateway (#29970) | ||
|
|
85e7b7baf1 |
fix(rag): reject non-finite GraphRAG embeddings (#29959) | ||
|
|
a3a6cec952 |
docs: document Postgres load and tuning for durable agents (#29946) | ||
|
|
a6d7cf6859 |
docs(models): clarify how to use Azure and Bedrock model strings (#29950) | ||
|
|
6b8f215e1f |
fix(core): prepare tool schemas for strict Azure OpenAI requests (#29953) |