@mastra/server 1.72.0-alpha.8 → 1.72.0

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.72.0-alpha.8"
+  version: "1.72.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.72.0-alpha.8",
+  "version": "1.72.0",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-observability-tracing-trace-query.md

@@ -283,21 +283,21 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
 
 ## Fields and operators
 
-| Predicate context | Fields                                                                                                                                                       | Operators                                                                  |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `entityName`, `entityType`, `environment`, `status`                                                                     | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace metadata    | `metadata.<key>`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace             | `startedAt`, `endedAt`, `durationMs`                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Trace             | `tags`                                                                                                                                                       | `includes`, `notIncludes`, `exists`, `notExists`                           |
-| Span              | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Span              | `startedAt`, `endedAt`, `durationMs`                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Span              | `error`                                                                                                                                                      | `exists`, `notExists`                                                      |
-| Score             | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                                                | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Score             | `score`, `timestamp`                                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Score             | `spanId`                                                                                                                                                     | `exists`, `notExists`                                                      |
-| Feedback          | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                            | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Feedback          | `value`, `timestamp`                                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Feedback          | `comment`                                                                                                                                                    | `exists`, `notExists`                                                      |
+| Predicate context | Fields                                                                                                                                                                                                         | Operators                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityName`, `entityType`, `environment`, `status`                                                                     | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace metadata    | `metadata.<key>`                                                                                                                                                                                               | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `startedAt`, `endedAt`, `durationMs`                                                                                                                                                                           | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Trace             | `tags`                                                                                                                                                                                                         | `includes`, `notIncludes`, `exists`, `notExists`                           |
+| Span              | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`, `runId`, `sessionId`, `userId`, `organizationId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Span              | `startedAt`, `endedAt`, `durationMs`                                                                                                                                                                           | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Span              | `error`                                                                                                                                                                                                        | `exists`, `notExists`                                                      |
+| Score             | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                                                                                                  | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Score             | `score`, `timestamp`                                                                                                                                                                                           | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Score             | `spanId`                                                                                                                                                                                                       | `exists`, `notExists`                                                      |
+| Feedback          | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                                                                              | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Feedback          | `value`, `timestamp`                                                                                                                                                                                           | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Feedback          | `comment`                                                                                                                                                                                                      | `exists`, `notExists`                                                      |
 
 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).
 
@@ -319,6 +319,27 @@ This top-level predicate doesn't inspect child spans. In contrast, `spans.some`
 
 Trace queries exclude incomplete roots before evaluating predicates. As a result, `{ op: 'notExists', path: 'durationMs' }` doesn't find running traces or malformed roots without a usable `endedAt`.
 
+### Filter by context identifiers
+
+`runId`, `sessionId`, `userId`, and `organizationId` are available at trace scope and inside `spans.some` / `spans.none`. Trace-scope predicates read the current root span. Span-scope predicates bind to one related current span, so a run recorded only on a child span is found through `spans.some`:
+
+```typescript
+const sessionTracesWithRun = {
+  op: 'and',
+  args: [
+    { op: 'eq', left: { path: 'organizationId' }, right: { literal: 'org-123' } },
+    { op: 'eq', left: { path: 'sessionId' }, right: { literal: 'session-123' } },
+    {
+      spans: {
+        some: { op: 'eq', left: { path: 'runId' }, right: { literal: 'run-42' } },
+      },
+    },
+  ],
+}
+```
+
+These identifiers support `eq`, `ne`, `in`, `notIn`, `exists`, and `notExists`. Field discovery lists them, but value discovery doesn't return their recorded values. Stores advertise support through the `trace-query-context-ids` feature. A predicate on one of these fields against an older store returns `501` before storage runs, and field discovery omits them for that store.
+
 ### Filter by span properties
 
 Every condition inside one `spans.some` or `spans.none` clause applies to the same current span. For example, this predicate finds a failed tool span whose name is `medication_lookup`; a matching name on one span and an error on another don't satisfy it:
@@ -679,7 +700,7 @@ const plan = planTraceQuery(parseTraceQueryRequest(request), {
 })
 ```
 
-`resourceId` is optional and narrows within the organization. Keyset and delta cursors are bound to the scope, so a cursor minted under one scope and reused under another returns `409` before storage runs. A scoped request against an observability store or `@mastra/core` that predates tenant scope returns `501` instead of running unscoped. Stores advertise support through the `trace-query-tenant-scope` feature. Callers can't name `organizationId` or `projectId` in predicates. Without a scope the routes behave as before, so self-hosted installations keep their own tenant model.
+`resourceId` is optional and narrows within the organization. Keyset and delta cursors are bound to the scope. A cursor created under one scope and reused under another returns `409` before storage runs. A scoped request against an observability store or `@mastra/core` that predates tenant scope returns `501` instead of running unscoped. Stores advertise support through the `trace-query-tenant-scope` feature. Callers can't name `projectId` in predicates. An `organizationId` predicate compares recorded data and is ANDed with the scope, so it can only narrow the tenant's own traces and never widens it. Without a scope the routes behave as before, so self-hosted installations keep their own tenant model.
 
 Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
 

package/dist/{observability-new-endpoints-Ct0CSLE4.cjs → observability-new-endpoints-7Zd6uEZf.cjs}

@@ -5,7 +5,7 @@ const require_constants = require("./constants-4IJp_uzj.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-BlGYb2fu.cjs");
+const require_system = require("./system-CskEzH1o.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");
@@ -1028,6 +1028,7 @@ const QUERY_TRACES = createNewRoute(require_server_handlers_observability_shared
 			observabilityStore = await require_server_handlers_observability_shared.getObservabilityStore(mastra);
 			require_server_handlers_observability_shared.assertObservabilityTraceQuerySupported(observabilityStore);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryRootDurationSupported(observabilityStore, plan.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryContextIdsSupported(observabilityStore, plan.where);
 			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) {
@@ -1078,6 +1079,105 @@ if (QUERY_TRACES.openapi) {
 		content: { "application/json": { schema: traceQueryTimeoutErrorSchema } }
 	};
 }
+const traceAggregateUnsupportedErrorSchema = zod_v4.z.object({
+	code: zod_v4.z.literal("TRACE_AGGREGATE_UNSUPPORTED"),
+	message: zod_v4.z.string()
+}).strict();
+/** Never echoes caller input: only the predicate-complexity issue keeps its own fixed message. */
+const traceAggregateValidationError = (error) => ({
+	status: 422,
+	body: {
+		code: "TRACE_QUERY_INVALID",
+		message: "The trace aggregate query is invalid",
+		issues: error.issues.map((issue) => {
+			const predicateTooComplex = issue.code === "custom" && issue.message === _mastra_core_storage.TRACE_QUERY_PREDICATE_COMPLEXITY_MESSAGE;
+			return {
+				code: predicateTooComplex ? "predicate_too_complex" : "invalid_request",
+				path: issue.path.map((part) => typeof part === "symbol" ? String(part) : part),
+				message: predicateTooComplex ? _mastra_core_storage.TRACE_QUERY_PREDICATE_COMPLEXITY_MESSAGE : "The value does not match the trace-aggregate request contract"
+			};
+		})
+	}
+});
+const AGGREGATE_TRACES = createNewRoute(require_server_handlers_observability_shared.NEW_ROUTE_DEFS.AGGREGATE_TRACES, {
+	bodySchema: _mastra_core_storage.traceAggregateRequestSchema,
+	responseSchema: _mastra_core_storage.traceAggregateResponseSchema,
+	onValidationError: traceAggregateValidationError,
+	maxBodySize: 256 * 1024,
+	preserveHttpExceptions: true,
+	isCoreSupported: require_server_handlers_observability_shared.supportsTraceAggregateCore,
+	onUnsupportedCore: () => throwTraceQueryError(501, {
+		code: "TRACE_AGGREGATE_UNSUPPORTED",
+		message: "Trace aggregation requires a newer @mastra/core. Please upgrade."
+	}),
+	handler: async ({ mastra, requestContext, timeRange, where, groupBy, interval, measures, having, orderBy, limit }) => {
+		let plan;
+		try {
+			plan = _mastra_core_storage.planTraceAggregate({
+				timeRange,
+				where,
+				groupBy,
+				interval,
+				measures,
+				having,
+				orderBy,
+				limit
+			}, { scope: resolveTraceQueryScope(requestContext, "TRACE_AGGREGATE_UNSUPPORTED") });
+		} catch (error) {
+			if (error instanceof _mastra_core_storage.TraceQueryValidationError) throwTraceQueryError(422, {
+				code: error.code,
+				message: error.message,
+				issues: error.issues
+			});
+			throw error;
+		}
+		let observabilityStore;
+		try {
+			observabilityStore = await require_server_handlers_observability_shared.getObservabilityStore(mastra);
+			require_server_handlers_observability_shared.assertObservabilityTraceAggregateSupported(observabilityStore);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryRootDurationSupported(observabilityStore, plan.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryContextIdsSupported(observabilityStore, plan.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryTenantScopeSupported(observabilityStore, plan.scope);
+		} catch (error) {
+			if (error instanceof require_http_exception.HTTPException && error.status === 501) throwTraceQueryError(501, {
+				code: "TRACE_AGGREGATE_UNSUPPORTED",
+				message: error.message
+			});
+			throw error;
+		}
+		try {
+			return await observabilityStore.aggregateTraces(plan);
+		} catch (error) {
+			if (error instanceof _mastra_core_storage.TraceQueryExecutionError) throwTraceQueryError(504, {
+				code: error.code,
+				message: error.message
+			});
+			throw error;
+		}
+	}
+});
+if (AGGREGATE_TRACES.openapi) {
+	AGGREGATE_TRACES.openapi.responses[400] = {
+		description: "Malformed JSON",
+		content: { "application/json": { schema: traceQueryMalformedBodyErrorSchema } }
+	};
+	AGGREGATE_TRACES.openapi.responses[413] = {
+		description: "Request body exceeds 256 KiB",
+		content: { "application/json": { schema: traceQueryBodyTooLargeErrorSchema } }
+	};
+	AGGREGATE_TRACES.openapi.responses[422] = {
+		description: "Structurally or semantically invalid trace aggregate query",
+		content: { "application/json": { schema: traceQueryValidationResponseSchema } }
+	};
+	AGGREGATE_TRACES.openapi.responses[501] = {
+		description: "The configured observability store does not support trace aggregation",
+		content: { "application/json": { schema: traceAggregateUnsupportedErrorSchema } }
+	};
+	AGGREGATE_TRACES.openapi.responses[504] = {
+		description: "Trace aggregate query exceeded the configured database execution timeout",
+		content: { "application/json": { schema: traceQueryTimeoutErrorSchema } }
+	};
+}
 const GET_TRACE_QUERY_FIELDS = createNewRoute(require_server_handlers_observability_shared.NEW_ROUTE_DEFS.GET_TRACE_QUERY_FIELDS, {
 	bodySchema: _mastra_core_storage.getTraceQueryFieldsArgsSchema,
 	responseSchema: _mastra_core_storage.getTraceQueryFieldsResponseSchema,
@@ -1109,7 +1209,7 @@ const GET_TRACE_QUERY_FIELDS = createNewRoute(require_server_handlers_observabil
 		try {
 			const observed = await observabilityStore.getTraceQueryObservedFields(plan);
 			return {
-				canonicalFields: _mastra_core_storage.getTraceQueryCanonicalFieldDescriptors(predicateScope, search).filter((field) => predicateScope !== "trace" || field.path !== "durationMs" || require_server_handlers_observability_shared.supportsObservabilityTraceQueryRootDuration(observabilityStore)),
+				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)),
 				...observed
 			};
 		} catch (error) {
@@ -1226,7 +1326,9 @@ const QUERY_THREADS = createNewRoute(require_server_handlers_observability_share
 			observabilityStore = await require_server_handlers_observability_shared.getObservabilityStore(mastra);
 			require_server_handlers_observability_shared.assertObservabilityThreadQuerySupported(observabilityStore);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryRootDurationSupported(observabilityStore, plan.traces.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryContextIdsSupported(observabilityStore, plan.traces.where);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryRootDurationSupported(observabilityStore, plan.where);
+			require_server_handlers_observability_shared.assertObservabilityTraceQueryContextIdsSupported(observabilityStore, plan.where);
 			require_server_handlers_observability_shared.assertObservabilityTraceQueryTenantScopeSupported(observabilityStore, plan.scope);
 		} catch (error) {
 			if (error instanceof require_http_exception.HTTPException && error.status === 501) throwTraceQueryError(501, {
@@ -1686,6 +1788,12 @@ const NEW_ROUTES = {
 	GET_CAPABILITIES
 };
 //#endregion
+Object.defineProperty(exports, "AGGREGATE_TRACES", {
+	enumerable: true,
+	get: function() {
+		return AGGREGATE_TRACES;
+	}
+});
 Object.defineProperty(exports, "CREATE_FEEDBACK", {
 	enumerable: true,
 	get: function() {
@@ -1903,4 +2011,4 @@ Object.defineProperty(exports, "UPDATE_FEEDBACK_REVIEW_STATUS", {
 	}
 });
 
-//# sourceMappingURL=observability-new-endpoints-Ct0CSLE4.cjs.map
+//# sourceMappingURL=observability-new-endpoints-7Zd6uEZf.cjs.map