@mastra/server 1.79.0-alpha.7 → 1.79.0-alpha.9

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-server
 description: Documentation for @mastra/server. Use when working with @mastra/server APIs, configuration, or implementation.
 metadata:
   package: "@mastra/server"
-  version: "1.79.0-alpha.7"
+  version: "1.79.0-alpha.9"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.79.0-alpha.7",
+  "version": "1.79.0-alpha.9",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-guides-mcp-authentication-authorization.md

@@ -47,7 +47,7 @@ A separate provider per MCP server does one thing and not another:
 
 The specification recommends support for **Client ID Metadata Documents (CIMD)**, which identify a client through an HTTPS metadata URL. It also defines pre-registration. Clients that support all registration options should prefer existing pre-registered information when available. Legacy Dynamic Client Registration (DCR) remains optional for compatibility but is deprecated for new implementations. See the versioned [client registration rules](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration).
 
-Mastra's provider accepts pre-registered client information and supports a DCR-based flow. Don't infer CIMD support from the presence of OAuth support. Check the registration mechanism supported by your client integration and authorization server before choosing a deployment.
+`MCPOAuthClientProvider` never registers a client at runtime and doesn't support DCR. Configure exactly one client identity: `clientInformation` for a client pre-registered with the authorization server, or `clientMetadataUrl` for CIMD. Check that your authorization server supports the mechanism you choose before deploying. See the [OAuth client reference](https://mastra.ai/reference/tools/mcp-client) for configuration examples.
 
 Mastra's interactive `authenticate()` flow uses a local loopback callback server. It isn't a hosted multi-user login endpoint. A hosted application must own its callback endpoint and associate each authorization attempt with the correct user and provider. See [interactive browser authentication](https://mastra.ai/reference/tools/mcp-client).
 
@@ -97,7 +97,7 @@ Protecting Mastra routes with `server.auth` and providing interoperable OAuth di
 
 Alongside the MCP transport, Mastra registers REST routes used by Studio to list servers, inspect tools, execute tools, and read resources. See the [MCP routes reference](https://mastra.ai/reference/server/routes) for the full list. These paths use the default `/api` prefix.
 
-The `POST /api/mcp/:serverId/tools/:toolId/execute` route calls `executeTool()` directly, without a protocol client. With a Mastra FGA provider configured, `MCPServer.executeTool()` enforces tool execution permission using the user in `requestContext`. The REST tool list also filters tools through FGA. These permission checks don't replace route authentication.
+The `POST /api/mcp/:serverId/tools/:toolId/execute` route calls `executeTool()` directly, without a protocol client. With a Mastra FGA provider configured, `MCPServer.executeTool()` enforces tool execution permission using the user in `requestContext`. The REST tool list also filters tools through FGA, but these permission checks don't replace route authentication.
 
 Built-in authentication for these routes depends on `server.auth`. Without it, `requiresAuth: true` doesn't enforce authentication. Custom middleware that checks only the `/mcp` or `/sse` transport paths leaves the REST routes open. If you use custom middleware instead of `server.auth`, default-deny `/api/mcp/*` and allow access only after authentication.
 

package/dist/docs/references/reference-observability-tracing-advanced-queries.md

@@ -21,18 +21,20 @@ For hosted traces, see [Query observability data on Mastra Platform](https://mas
 
 The configured observability store must support each API. Call `getObservabilityCapabilities()` or `GET /api/observability/capabilities` and check these flags before showing a feature:
 
-| Capability                   | Store feature                     | Enables                                                                                |
-| ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `traceQuery`                 | `trace-query`                     | `queryTraces()`                                                                        |
-| `traceAggregate`             | `trace-aggregate`                 | `aggregateTraces()`                                                                    |
-| `traceQueryRootDuration`     | `trace-query-root-duration`       | Trace-scope `durationMs` predicates                                                    |
-| `traceQueryTimeToFirstChunk` | `trace-query-time-to-first-chunk` | `timeToFirstChunkMs` predicates and results                                            |
-| `traceQueryContextIds`       | `trace-query-context-ids`         | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
-| `traceQueryRootSpanFields`   | `trace-query-root-span-fields`    | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
-| `traceQueryDiscovery`        | `trace-query-discovery`           | [Field and value discovery](#discover-fields-and-values)                               |
-| `traceQueryTenantScope`      | `trace-query-tenant-scope`        | [Trusted tenant scope](#trusted-tenant-scope)                                          |
-
-A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name` and `spanType` are the exception and return `422` with a `field_not_allowed` issue.
+| Capability                       | Store feature                          | Enables                                                                                |
+| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `traceQuery`                     | `trace-query`                          | `queryTraces()`                                                                        |
+| `traceAggregate`                 | `trace-aggregate`                      | `aggregateTraces()`                                                                    |
+| `traceQueryRootDuration`         | `trace-query-root-duration`            | Trace-scope `durationMs` predicates                                                    |
+| `traceQueryTimeToFirstChunk`     | `trace-query-time-to-first-chunk`      | `timeToFirstChunkMs` predicates and results                                            |
+| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                      |
+| `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
+| `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
+| `traceQueryRootEntityId`         | `trace-query-root-entity-id`           | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures            |
+| `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                               |
+| `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                          |
+
+A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name`, `spanType`, and `entityId` are the exception and return `422` with a `field_not_allowed` issue.
 
 ## Select traces
 
@@ -75,7 +77,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 
 | Predicate context | Fields                                                                                                                                                                                                 | Operators                                                                  |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                                         | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace metadata    | `metadata.<key>`                                                                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Trace             | `tags`                                                                                                                                                                                                 | `includes`, `notIncludes`, `exists`, `notExists`                           |
@@ -84,7 +86,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 | Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Span              | `error`                                                                                                                                                                                                | `exists`, `notExists`                                                      |
 
-Trace-scope `name` and `spanType` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
+Trace-scope `name`, `spanType`, and `entityId` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
 
 Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`. Tag predicates name the stored tag collection in `path`. `includes` and `notIncludes` also take one tag in `value`, while `exists` and `notExists` take only `op` and `path`. See [Filter by tags](#filter-by-tags). Text predicates use the comparison shape with a string literal. See [Filter by text](#filter-by-text).
 
@@ -128,7 +130,13 @@ const slowFirstChunk = {
 
 The value is `null` when the span didn't stream a chunk, for example a tool call or a workflow run. A `null` value counts as missing, so it matches `notExists` and never matches ordered predicates. A value of `0` isn't missing. It means the first chunk arrived in the same millisecond the span started.
 
-Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Sorting by this field isn't supported. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+
+#### Sort by time to first chunk
+
+Pass `orderBy: [{ field: 'timeToFirstChunkMs', direction: 'desc' }]` to list the slowest first chunks first. Traces sort by the root span's value. Missing values sort last in both directions, and `0` sorts as a value. Ties break by `traceId` for traces and by span identity for `querySpans()`.
+
+Stores advertise the sort through the `trace-query-time-to-first-chunk-sort` feature, and the server reports it as the `traceQueryTimeToFirstChunkSort` capability. Against an older store, the sort returns `501` before storage runs.
 
 #### Filter by context identifiers
 
@@ -437,16 +445,16 @@ curl --request POST \
 
 ### Request fields
 
-| Field        | Required | Description                                                                                                                                     |
-| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`. |
-| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                 |
-| `orderBy`    | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode.      |
-| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                            |
-| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                         |
-| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                |
-| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                           |
-| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                            |
+| Field        | Required | Description                                                                                                                                                       |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`.                   |
+| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                                   |
+| `orderBy`    | No       | One item ordering results by `startedAt`, `endedAt`, or `timeToFirstChunkMs`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode. |
+| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                              |
+| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                                           |
+| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                                  |
+| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                                             |
+| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                                              |
 
 Unknown fields are rejected. Requests can't select a projection, declare joins, request counts or measures, or control authorization. Use [`aggregateTraces()`](#aggregate-traces) for counts and measures. Request bodies are limited to 256 KiB.
 
@@ -657,12 +665,13 @@ Unknown fields are rejected. Aggregation isn't paginated. Narrow the selection,
 
 Dimensions read the current root span of each selected trace:
 
-| Dimension                                                                             | Notes                                                                                                            |
-| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                            |
-| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                   |
-| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                     |
-| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`. |
+| Dimension                                                                             | Notes                                                                                                                                |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                                                |
+| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                                       |
+| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                                         |
+| `entityId`                                                                            | Root span entity ID. Groups traces that have no `entityName`, such as scorer runs. Requires the `traceQueryRootEntityId` capability. |
+| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`.                     |
 
 Every dimension except `serviceName`, `executionSource`, and `experimentId` is also a trace-scope `where` field, so you can drill into a group by adding its values to the predicate. `traceId`, `spanId`, `runId`, and `requestId` aren't groupable. Traces with no value for a dimension form their own group with a `null` value.
 

package/dist/{observability-new-endpoints-s3ccgoif.cjs → observability-new-endpoints-AMp9bnMV.cjs}

@@ -5,7 +5,7 @@ const require_constants = require("./constants-e7aaPCLj.cjs");
 const require_server_handlers_error = require("./server/handlers/error.cjs");
 const require_server_handlers_observability_list_query_schemas = require("./server/handlers/observability-list-query-schemas.cjs");
 const require_server_handlers_observability_shared = require("./server/handlers/observability-shared.cjs");
-const require_system = require("./system-wG9idyeI.cjs");
+const require_system = require("./system-BvpFMIJB.cjs");
 const require_server_handlers_author_enrichment = require("./server/handlers/author-enrichment.cjs");
 const require_server_handlers_authorship = require("./server/handlers/authorship.cjs");
 let zod_v4 = require("zod/v4");
@@ -1034,6 +1034,7 @@ const QUERY_TRACES = createNewRoute(require_server_handlers_observability_shared
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryContextIdsSupported(observabilityStore, plan.where);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryTimeToFirstChunkSupported(observabilityStore, plan.where);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryRootSpanFieldsSupported(observabilityStore, plan);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryTimeToFirstChunkSortSupported(observabilityStore, plan.orderBy);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryTenantScopeSupported(observabilityStore, plan.scope);
 			if (plan.paginationMode === "delta" && !observabilityStore.getFeatures()?.includes("delta-polling")) throw new require_http_exception.HTTPException(501, { message: "This storage provider does not support observability delta polling" });
 		} catch (error) {
@@ -1249,6 +1250,7 @@ const QUERY_SPANS = createNewRoute(require_server_handlers_observability_shared.
 			require_server_handlers_observability_shared.assertObservabilitySpanQuerySupported(observabilityStore);
 			require_server_handlers_observability_shared.assertObservabilitySpanQueryFieldsSupported(observabilityStore, plan.where);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryTimeToFirstChunkSupported(observabilityStore, plan.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryTimeToFirstChunkSortSupported(observabilityStore, plan.orderBy);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryTenantScopeSupported(observabilityStore, plan.scope);
 		} catch (error) {
 			if (error instanceof _mastra_core_storage.TraceQueryValidationError) throwTraceQueryError(422, {
@@ -1341,13 +1343,13 @@ const GET_TRACE_QUERY_FIELDS = createNewRoute(require_server_handlers_observabil
 		}
 		try {
 			const observed = await observabilityStore.getTraceQueryObservedFields(plan);
-			const canonicalFields = _mastra_core_storage.getTraceQueryCanonicalFieldDescriptors(predicateScope, search).filter((field) => predicateScope !== "trace" || field.path !== "durationMs" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootDuration(observabilityStore)).filter((field) => !require_server_handlers_observability_shared.isTraceQueryContextIdField(field.path) || require_server_handlers_observability_shared.supportsObservabilityTraceQueryContextIds(observabilityStore)).filter((field) => field.path !== "timeToFirstChunkMs" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryTimeToFirstChunk(observabilityStore)).filter((field) => predicateScope !== "trace" || !require_server_handlers_observability_shared.isTraceQueryRootSpanField(field.path) || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootSpanFields(observabilityStore));
+			const canonicalFields = _mastra_core_storage.getTraceQueryCanonicalFieldDescriptors(predicateScope, search).filter((field) => predicateScope !== "trace" || field.path !== "durationMs" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootDuration(observabilityStore)).filter((field) => !require_server_handlers_observability_shared.isTraceQueryContextIdField(field.path) || require_server_handlers_observability_shared.supportsObservabilityTraceQueryContextIds(observabilityStore)).filter((field) => field.path !== "timeToFirstChunkMs" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryTimeToFirstChunk(observabilityStore)).filter((field) => predicateScope !== "trace" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootSpanField(observabilityStore, field.path));
 			const describesAggregate = predicateScope === "trace" && require_server_handlers_observability_shared.supportsTraceAggregateCore() && _mastra_core_storage.traceAggregateDiscoverySchema !== void 0 && require_server_handlers_observability_shared.supportsObservabilityTraceAggregate(observabilityStore);
 			return {
 				canonicalFields,
 				...observed,
 				...describesAggregate && { aggregate: {
-					dimensions: _mastra_core_storage.getTraceAggregateDimensionDescriptors().filter((dimension) => !require_server_handlers_observability_shared.isTraceQueryRootSpanField(dimension.path) || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootSpanFields(observabilityStore)),
+					dimensions: _mastra_core_storage.getTraceAggregateDimensionDescriptors().filter((dimension) => require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootSpanField(observabilityStore, dimension.path)),
 					measures: _mastra_core_storage.getTraceAggregateMeasureDescriptors()
 				} }
 			};
@@ -2199,4 +2201,4 @@ Object.defineProperty(exports, "UPDATE_FEEDBACK_REVIEW_STATUS", {
 	}
 });
 
-//# sourceMappingURL=observability-new-endpoints-s3ccgoif.cjs.map
+//# sourceMappingURL=observability-new-endpoints-AMp9bnMV.cjs.map