@mastra/server 1.66.0-alpha.0 → 1.66.0-alpha.1

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.66.0-alpha.0"
+  version: "1.66.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -24,6 +24,7 @@ const result = await mastraClient.queryTraces({
         op: 'and',
         args: [
           { op: 'eq', left: { path: 'scorerId' }, right: { literal: 'factuality' } },
+          { op: 'eq', left: { path: 'scorerVersion' }, right: { literal: '2.1.0' } },
           { op: 'lt', left: { path: 'score' }, right: { literal: 0.6 } },
         ],
       },
@@ -34,7 +35,7 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
-A `some` clause matches when one related record satisfies its complete nested predicate. In this example, `scorerId` and `score` must match on the same score record. A `none` clause matches when no related record satisfies its complete nested predicate.
+A `some` clause matches when one related record satisfies its complete nested predicate. In this example, `scorerId`, `scorerVersion`, and `score` must match on the same score record. A `none` clause uses anti-existence semantics: it matches when no related record satisfies its complete nested predicate. A trace with no related scores therefore matches `scores.none`.
 
 Span clauses examine the current root span and current child spans. The root `timeRange` applies only to the selected current root's `startedAt`. Related spans and scores can participate even when their own timestamps are outside that range. Related records correlate only through a matching non-null `traceId`.
 
@@ -99,17 +100,176 @@ 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             | `startedAt`, `endedAt`                                                                   | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Span              | `spanType`                                                                               | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Span              | `error`                                                                                  | `exists`, `notExists`                                                      |
-| Score             | `scorerId`                                                                               | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Score             | `score`                                                                                  | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| 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`                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `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`                                                      |
 
 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`.
 
+String comparisons are case-sensitive, and literals are never coerced. Canonical string fields compare exact stored values. Metadata string values are trimmed before comparison, as described below. Numeric predicates, including `score` and `durationMs`, require numbers, while timestamp predicates require ISO timestamp strings. A missing value satisfies neither positive nor ordered predicates, although it does satisfy the negative operators `ne` and `notIn`. Combine a negative predicate with `exists` when the field must also be present.
+
+### 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:
+
+```typescript
+const failedMedicationLookup = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'name' }, right: { literal: 'medication_lookup' } },
+        { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+        { op: 'exists', path: 'error' },
+      ],
+    },
+  },
+}
+```
+
+Use `status` for the derived `success` or `error` outcome. Use `error` when you only need to test whether error details are present.
+
+`durationMs` is the span's elapsed time in milliseconds. Span `startedAt` and `endedAt` conditions filter related spans independently of the top-level root `timeRange`:
+
+```typescript
+const slowModelCalls = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'spanType' }, right: { literal: 'model_generation' } },
+        { op: 'gt', left: { path: 'durationMs' }, right: { literal: 5000 } },
+        {
+          op: 'gte',
+          left: { path: 'startedAt' },
+          right: { literal: '2026-07-15T00:00:00.000Z' },
+        },
+      ],
+    },
+  },
+}
+```
+
+`model` and `provider` read the canonical `attributes.model` and `attributes.provider` span attributes. Only stored string values are queryable; missing, null, and non-string values count as missing.
+
+```typescript
+const selectedModel = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        {
+          op: 'eq',
+          left: { path: 'model' },
+          right: { literal: 'claude-sonnet-4-6' },
+        },
+        { op: 'eq', left: { path: 'provider' }, right: { literal: 'anthropic' } },
+      ],
+    },
+  },
+}
+```
+
+Use generic entity fields for tool and retrieval identity. The version fields let one clause qualify the same span by its entity lineage:
+
+```typescript
+const versionedRetrieval = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'entityType' }, right: { literal: 'rag_ingestion' } },
+        { op: 'eq', left: { path: 'entityId' }, right: { literal: 'medication-index' } },
+        { op: 'eq', left: { path: 'entityVersionId' }, right: { literal: 'index-v3' } },
+        { op: 'eq', left: { path: 'rootEntityVersionId' }, right: { literal: 'agent-v2' } },
+      ],
+    },
+  },
+}
+```
+
+### Filter by score time
+
+Score timestamps are independent of the required top-level trace `timeRange`. The top-level range selects trace candidates by trace start time. A nested `timestamp` predicate limits related score records:
+
+```typescript
+const query = {
+  timeRange: {
+    from: '2026-08-01T00:00:00.000Z',
+    to: '2026-08-08T00:00:00.000Z',
+  },
+  where: {
+    scores: {
+      some: {
+        op: 'and',
+        args: [
+          { op: 'eq', left: { path: 'scoreSource' }, right: { literal: 'automated' } },
+          {
+            op: 'gte',
+            left: { path: 'timestamp' },
+            right: { literal: '2026-07-15T00:00:00.000Z' },
+          },
+          {
+            op: 'lt',
+            left: { path: 'timestamp' },
+            right: { literal: '2026-08-01T00:00:00.000Z' },
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### Filter by span anchoring
+
+Use `spanId` only to test whether a score targets a span. The predicate doesn't join the score to a matching span predicate:
+
+```typescript
+// At least one score targets a span.
+const anchoredToSpanWhere = { scores: { some: { op: 'exists', path: 'spanId' } } }
+
+// At least one score applies to the trace rather than a span.
+const traceLevelScoreWhere = { scores: { some: { op: 'notExists', path: 'spanId' } } }
+```
+
+The deprecated `source` field and `scorerName` aren't available as score predicate fields. Use the canonical `scoreSource` and `scorerId` fields.
+
+### Filter by metadata
+
+Use `metadata.<key>` paths for custom dimensions stored on the current root span. Metadata predicates compare trimmed, non-empty string values exactly and case-sensitively. Leading and trailing whitespace in a stored string value is ignored. Values empty after trimming count as missing. Null, numeric, boolean, object, and array values also count as missing.
+
+```typescript
+const messageTrace = {
+  op: 'and',
+  args: [
+    { op: 'eq', left: { path: 'metadata.messageId' }, right: { literal: 'message-123' } },
+    { op: 'in', value: { path: 'metadata.actorRole' }, set: ['assistant', 'tool'] },
+    { op: 'exists', path: 'metadata.protocolVersion' },
+    {
+      op: 'or',
+      args: [
+        { op: 'eq', left: { path: 'metadata.temporalRunId' }, right: { literal: 'run-456' } },
+        { op: 'eq', left: { path: 'metadata.externalTraceId' }, right: { literal: 'trace-789' } },
+      ],
+    },
+    { op: 'not', arg: { op: 'exists', path: 'metadata.parentMessageId' } },
+  ],
+}
+```
+
+The key must name one top-level property. Empty keys and nested paths are rejected. Metadata keys aren't trimmed, so leading and trailing whitespace remains part of the exact key identity. When metadata duplicates a canonical trace field, such as `resourceId`, `threadId`, or `environment`, prefer the canonical field because it uses the dedicated storage column. The `metadata.<key>` form remains available when you specifically need the value from the metadata object. Metadata and canonical values may differ.
+
+Metadata fields aren't available for grouping or field discovery.
+
 ## Responses
 
 An ungrouped query returns only lightweight completed traces:

package/dist/server/handlers/agent-builder.cjs

@@ -30,7 +30,7 @@ var agent_builder_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll
 });
 let agentBuilderWorkflowsPromise;
 async function loadAgentBuilderWorkflows() {
-	agentBuilderWorkflowsPromise ??= Promise.resolve().then(() => require("../../dist-BnPncT17.cjs")).then((mod) => mod.agentBuilderWorkflows);
+	agentBuilderWorkflowsPromise ??= Promise.resolve().then(() => require("../../dist-BmrsK_KX.cjs")).then((mod) => mod.agentBuilderWorkflows);
 	return agentBuilderWorkflowsPromise;
 }
 async function registerAgentBuilderWorkflows(mastra) {

package/dist/server/handlers/agent-builder.js

@@ -29,7 +29,7 @@ var agent_builder_exports = /* @__PURE__ */ __exportAll({
 });
 let agentBuilderWorkflowsPromise;
 async function loadAgentBuilderWorkflows() {
-	agentBuilderWorkflowsPromise ??= import("../../dist-CX9x93MJ.js").then((mod) => mod.agentBuilderWorkflows);
+	agentBuilderWorkflowsPromise ??= import("../../dist-4Qm6OSPJ.js").then((mod) => mod.agentBuilderWorkflows);
 	return agentBuilderWorkflowsPromise;
 }
 async function registerAgentBuilderWorkflows(mastra) {

package/dist/server/handlers/datasets.cjs

@@ -5,7 +5,7 @@ const require_common = require("../../common-DQn8jX5T.cjs");
 const require_route_builder = require("../../route-builder-C8n4ugUf.cjs");
 const require_constants = require("../../constants-4IJp_uzj.cjs");
 const require_server_handlers_error = require("./error.cjs");
-const require_datasets = require("../../datasets-BVbtevHd.cjs");
+const require_datasets = require("../../datasets-C-_ZWnxR.cjs");
 let zod = require("zod");
 let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_error = require("@mastra/core/error");
@@ -797,7 +797,7 @@ const LIST_EXPERIMENT_RESULTS_ROUTE = require_route_builder.createRoute({
 	path: "/datasets/:datasetId/experiments/:experimentId/results",
 	responseType: "json",
 	pathParamSchema: require_datasets.datasetAndExperimentIdPathParams,
-	queryParamSchema: require_datasets.paginationQuerySchema,
+	queryParamSchema: require_datasets.listExperimentResultsQuerySchema,
 	responseSchema: require_datasets.listExperimentResultsResponseSchema,
 	summary: "List experiment results",
 	description: "Returns a paginated list of results for the experiment",
@@ -806,14 +806,15 @@ const LIST_EXPERIMENT_RESULTS_ROUTE = require_route_builder.createRoute({
 	handler: async ({ mastra, datasetId, experimentId, ...params }) => {
 		assertDatasetsAvailable();
 		try {
-			const { page, perPage } = params;
+			const { page, perPage, tags } = params;
 			const ds = await mastra.datasets.get({ id: datasetId });
 			const run = await ds.getExperiment({ experimentId });
 			if (!run || run.datasetId !== datasetId) throw new require_http_exception.HTTPException(404, { message: `Experiment not found: ${experimentId}` });
 			const result = await ds.listExperimentResults({
 				experimentId,
 				page: page ?? 0,
-				perPage: perPage ?? 10
+				perPage: perPage ?? 10,
+				...tags !== void 0 ? { tags } : {}
 			});
 			return {
 				results: result.results.map(({ experimentId: _eid, ...rest }) => ({