@mastra/server 1.80.0 → 1.81.0-alpha.0

package/dist/dist-_M1jEPcL.js

@@ -0,0 +1 @@
+export { n as openai } from "./dist-BLjE21MA.js";

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.80.0"
+  version: "1.81.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -30,6 +30,8 @@ The configured observability store must support each API. Call `getObservability
 | `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`                                                      |
+| `traceQueryTimeToFirstToken`     | `trace-query-time-to-first-token`      | `timeToFirstTokenMs` predicates and results                                            |
+| `traceQueryTimeToFirstTokenSort` | `trace-query-time-to-first-token-sort` | `orderBy` on `timeToFirstTokenMs`                                                      |
 | `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            |
@@ -81,18 +83,18 @@ Span clauses examine the current root span and current child spans. The root `ti
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
 | 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             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Trace             | `tags`                                                                                                                                                                                                 | `includes`, `notIncludes`, `exists`, `notExists`                           |
 | Span              | `name`                                                                                                                                                                                                 | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`, `matches`, `notMatches`  |
 | Span              | `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`, `runId`, `sessionId`, `userId`, `organizationId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Span              | `error`                                                                                                                                                                                                | `exists`, `notExists`                                                      |
 
 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).
 
-String comparisons are case-sensitive, and literals are never coerced. `matches` and `notMatches` are the exception: they compare words case-insensitively. Canonical string fields compare exact stored values. Metadata string values are trimmed before comparison, as described below. Duration and time-to-first-chunk predicates 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.
+String comparisons are case-sensitive, and literals are never coerced. `matches` and `notMatches` are the exception: they compare words case-insensitively. Canonical string fields compare exact stored values. Metadata string values are trimmed before comparison, as described below. Duration, time-to-first-chunk, and time-to-first-token predicates 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 root duration
 
@@ -140,6 +142,20 @@ Pass `orderBy: [{ field: 'timeToFirstChunkMs', direction: 'desc' }]` to list the
 
 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 and sort by time to first token
+
+`timeToFirstTokenMs` is the time in milliseconds from the start of a model call, the provider request itself, to the first chunk that call streams. It leaves out the work Mastra does before calling the model, such as input processors. The value is measured once, on the model inference span that streamed the chunk. Model step, model generation, and agent run spans carry the value of the nearest such inference below them: each step takes its own, and the generation and agent run take the first step's. A step can run more than one inference, for example a fallback model or a retry that opens a new inference span. The value then comes from the first inference that streamed a chunk. A fallback attempt that failed ends its inference span with its error. That span has a value only if it streamed a chunk first. Mastra storage keeps the value in its own column and leaves it out of the stored `attributes`. Read it from the span's `timeToFirstTokenMs` field. When an in-process agent retries a failed model call, the AI SDK retries inside a single inference span. The value then includes the failed attempt and the retry wait. Durable agents open one inference span per attempt and don't. At trace scope, the field reads the current root span's value. Inside `spans.some` or `spans.none`, it reads each related span.
+
+This predicate finds traces whose root agent waited more than 2 seconds for the model's first token:
+
+```typescript
+const slowFirstToken = { op: 'gt', left: { path: 'timeToFirstTokenMs' }, right: { literal: 2000 } }
+```
+
+`null`, `0`, and missing values follow the same rules as `timeToFirstChunkMs`. Pass `orderBy: [{ field: 'timeToFirstTokenMs', direction: 'desc' }]` to list the slowest first tokens first, with the same ordering and tie-breaks.
+
+Stores advertise support through the `trace-query-time-to-first-token` feature and the sort through the `trace-query-time-to-first-token-sort` feature. The server reports them as the `traceQueryTimeToFirstToken` and `traceQueryTimeToFirstTokenSort` capabilities. Against an older store, results omit the field, and a predicate or sort on it returns `501` before storage runs.
+
 #### 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`:
@@ -447,16 +463,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`, `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.                                                                              |
+| 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`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, 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.
 
@@ -478,14 +494,15 @@ A query using keyset pagination returns lightweight completed traces and a curso
       "entityType": "agent",
       "environment": "production",
       "status": "success",
-      "timeToFirstChunkMs": 412
+      "timeToFirstChunkMs": 412,
+      "timeToFirstTokenMs": 380
     }
   ],
   "page": { "next": null }
 }
 ```
 
-`timeToFirstChunkMs` is present only when the configured store supports it. See [Filter by time to first chunk](#filter-by-time-to-first-chunk).
+`timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter by time to first chunk](#filter-by-time-to-first-chunk) and [Filter and sort by time to first token](#filter-and-sort-by-time-to-first-token).
 
 The response doesn't include the related spans that matched the predicate. Use [`getTrace()`](https://mastra.ai/reference/client-js/observability) to load the full trace after selecting a result.
 
@@ -1005,7 +1022,7 @@ Value suggestions are available for these canonical fields:
 | Trace | `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`, `tags` |
 | Spans | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityName`   |
 
-Each executable top-level string `metadata.<key>` field also supports value suggestions in the `trace` scope. Identifiers, timestamps, durations, time to first chunk, errors, and version IDs don't. The fields response still includes canonical fields with `valueSuggestions: false`. The values endpoint rejects those paths with `422 TRACE_QUERY_INVALID`.
+Each executable top-level string `metadata.<key>` field also supports value suggestions in the `trace` scope. Identifiers, timestamps, durations, time to first chunk, time to first token, errors, and version IDs don't. The fields response still includes canonical fields with `valueSuggestions: false`. The values endpoint rejects those paths with `422 TRACE_QUERY_INVALID`.
 
 Both discovery requests require a half-open time range. They use the same current-record semantics as `queryTraces()`: qualifying completed roots satisfy `from <= startedAt < to`, and related values come only from current records joined to those roots by `traceId`. Discovery doesn't accept or apply a draft `where` predicate.
 

package/dist/{memory-DQXCDswv.js → memory-BTR95ujT.js}

@@ -1540,8 +1540,8 @@ const SEARCH_MEMORY_ROUTE = createRoute({
 				};
 				searchThreadId = threads[0].id;
 			}
-			const beforeRange = typeof config.semanticRecall === `boolean` ? 2 : typeof config.semanticRecall?.messageRange === `number` ? config.semanticRecall.messageRange : config.semanticRecall?.messageRange.before || 2;
-			const afterRange = typeof config.semanticRecall === `boolean` ? 2 : typeof config.semanticRecall?.messageRange === `number` ? config.semanticRecall.messageRange : config.semanticRecall?.messageRange.after || 2;
+			const beforeRange = typeof config.semanticRecall === `boolean` ? 2 : typeof config.semanticRecall?.messageRange === `number` ? config.semanticRecall.messageRange : config.semanticRecall?.messageRange?.before ?? 2;
+			const afterRange = typeof config.semanticRecall === `boolean` ? 2 : typeof config.semanticRecall?.messageRange === `number` ? config.semanticRecall.messageRange : config.semanticRecall?.messageRange?.after ?? 2;
 			if (resourceScope && config.semanticRecall) config.semanticRecall = typeof config.semanticRecall === `boolean` ? {
 				messageRange: 0,
 				topK: 2,
@@ -1734,4 +1734,4 @@ const DELETE_MESSAGES_NETWORK_ROUTE = createRoute({
 });
 export { TRANSFER_THREAD_ROUTE as C, getTextContent as D, UPDATE_WORKING_MEMORY_ROUTE as E, memory_exports as O, SEARCH_MEMORY_ROUTE as S, UPDATE_THREAD_ROUTE as T, LIST_MESSAGES_ROUTE as _, DELETE_MESSAGES_NETWORK_ROUTE as a, SAVE_MESSAGES_NETWORK_ROUTE as b, DELETE_THREAD_ROUTE as c, GET_MEMORY_STATUS_ROUTE as d, GET_OBSERVATIONAL_MEMORY_ROUTE as f, LIST_MESSAGES_NETWORK_ROUTE as g, GET_WORKING_MEMORY_ROUTE as h, CREATE_THREAD_ROUTE as i, GET_MEMORY_CONFIG_ROUTE as l, GET_THREAD_BY_ID_ROUTE as m, CLONE_THREAD_ROUTE as n, DELETE_MESSAGES_ROUTE as o, GET_THREAD_BY_ID_NETWORK_ROUTE as p, CREATE_THREAD_NETWORK_ROUTE as r, DELETE_THREAD_NETWORK_ROUTE as s, AWAIT_BUFFER_STATUS_ROUTE as t, GET_MEMORY_STATUS_NETWORK_ROUTE as u, LIST_THREADS_NETWORK_ROUTE as v, UPDATE_THREAD_NETWORK_ROUTE as w, SAVE_MESSAGES_ROUTE as x, LIST_THREADS_ROUTE as y };
 
-//# sourceMappingURL=memory-DQXCDswv.js.map
+//# sourceMappingURL=memory-BTR95ujT.js.map