@mastra/client-js 1.56.0-alpha.7 → 1.56.0-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/dist/docs/SKILL.md +1 -1
  2. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  3. package/dist/docs/references/reference-client-js-observability.md +2 -2
  4. package/dist/docs/references/reference-observability-tracing-advanced-queries.md +28 -21
  5. package/dist/route-types.generated.d.ts +4 -2
  6. package/dist/route-types.generated.d.ts.map +1 -1
  7. package/package.json +3 -3
package/dist/docs/SKILL.md CHANGED
@@ -3,7 +3,7 @@ name: mastra-client-js
3
3
  description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/client-js"
6
- version: "1.56.0-alpha.7"
6
+ version: "1.56.0-alpha.8"
7
7
  ---
8
8
 
9
9
  ## When to use
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.56.0-alpha.7",
2
+ "version": "1.56.0-alpha.8",
3
3
  "package": "@mastra/client-js",
4
4
  "exports": {},
5
5
  "modules": {}
package/dist/docs/references/reference-client-js-observability.md CHANGED
@@ -90,7 +90,7 @@ const result = await mastraClient.querySpans({
90
90
  console.log(result.spans)
91
91
  ```
92
92
 
93
- Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt` or `endedAt`, ascending or descending, and defaults to descending start time.
93
+ Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, or `timeToFirstChunkMs`, ascending or descending, and defaults to descending start time. Spans without a `timeToFirstChunkMs` value sort last in both directions.
94
94
 
95
95
  | Fields | Operators |
96
96
  | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -98,7 +98,7 @@ Pages default to 100 rows and allow at most 1,000. The response is `{ spans, pag
98
98
  | `organizationId`, `resourceId`, `runId`, `sessionId`, `userId`, `requestId`, `serviceName`, `experimentId`, `environment`, `executionSource` | Same string operators |
99
99
  | Entity, parent entity and root entity `Type`, `Id`, `Name`, `VersionId` fields, such as `parentEntityId` | Same string operators |
100
100
  | `name`, `spanType`, `status` | Same string operators; `name` also accepts `matches` / `notMatches` for normalized whole words and phrases |
101
- | `startedAt`, `endedAt`, `durationMs` | Comparisons, membership and presence |
101
+ | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs` | Comparisons, membership and presence |
102
102
  | `error` | `exists`, `notExists` |
103
103
 
104
104
  Combine predicates with `and`, `or` and `not`. Membership uses `{ op: 'in', value: { path: 'spanType' }, set: ['agent_run', 'tool_call'] }`. A span's status is `error` when it has an error and `success` otherwise.
package/dist/docs/references/reference-observability-tracing-advanced-queries.md CHANGED
@@ -21,16 +21,17 @@ For hosted traces, see [Query observability data on Mastra Platform](https://mas
21
21
 
22
22
  The configured observability store must support each API. Call `getObservabilityCapabilities()` or `GET /api/observability/capabilities` and check these flags before showing a feature:
23
23
 
24
- | Capability | Store feature | Enables |
25
- | ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
26
- | `traceQuery` | `trace-query` | `queryTraces()` |
27
- | `traceAggregate` | `trace-aggregate` | `aggregateTraces()` |
28
- | `traceQueryRootDuration` | `trace-query-root-duration` | Trace-scope `durationMs` predicates |
29
- | `traceQueryTimeToFirstChunk` | `trace-query-time-to-first-chunk` | `timeToFirstChunkMs` predicates and results |
30
- | `traceQueryContextIds` | `trace-query-context-ids` | `runId`, `sessionId`, `userId`, and `organizationId` predicates |
31
- | `traceQueryRootSpanFields` | `trace-query-root-span-fields` | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
32
- | `traceQueryDiscovery` | `trace-query-discovery` | [Field and value discovery](#discover-fields-and-values) |
33
- | `traceQueryTenantScope` | `trace-query-tenant-scope` | [Trusted tenant scope](#trusted-tenant-scope) |
24
+ | Capability | Store feature | Enables |
25
+ | -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
26
+ | `traceQuery` | `trace-query` | `queryTraces()` |
27
+ | `traceAggregate` | `trace-aggregate` | `aggregateTraces()` |
28
+ | `traceQueryRootDuration` | `trace-query-root-duration` | Trace-scope `durationMs` predicates |
29
+ | `traceQueryTimeToFirstChunk` | `trace-query-time-to-first-chunk` | `timeToFirstChunkMs` predicates and results |
30
+ | `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs` |
31
+ | `traceQueryContextIds` | `trace-query-context-ids` | `runId`, `sessionId`, `userId`, and `organizationId` predicates |
32
+ | `traceQueryRootSpanFields` | `trace-query-root-span-fields` | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
33
+ | `traceQueryDiscovery` | `trace-query-discovery` | [Field and value discovery](#discover-fields-and-values) |
34
+ | `traceQueryTenantScope` | `trace-query-tenant-scope` | [Trusted tenant scope](#trusted-tenant-scope) |
34
35
 
35
36
  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.
36
37
 
@@ -128,7 +129,13 @@ const slowFirstChunk = {
128
129
 
129
130
  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.
130
131
 
131
- 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.
132
+ 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.
133
+
134
+ #### Sort by time to first chunk
135
+
136
+ 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()`.
137
+
138
+ 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.
132
139
 
133
140
  #### Filter by context identifiers
134
141
 
@@ -437,16 +444,16 @@ curl --request POST \
437
444
 
438
445
  ### Request fields
439
446
 
440
- | Field | Required | Description |
441
- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
442
- | `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`. |
443
- | `where` | No | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses. |
444
- | `orderBy` | No | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode. |
445
- | `page` | No | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`. |
446
- | `pagination` | No | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100. |
447
- | `mode` | No | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`. |
448
- | `after` | No | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark. |
449
- | `limit` | No | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100. |
447
+ | Field | Required | Description |
448
+ | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
449
+ | `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`. |
450
+ | `where` | No | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses. |
451
+ | `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. |
452
+ | `page` | No | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`. |
453
+ | `pagination` | No | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100. |
454
+ | `mode` | No | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`. |
455
+ | `after` | No | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark. |
456
+ | `limit` | No | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100. |
450
457
 
451
458
  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.
452
459
 
package/dist/route-types.generated.d.ts CHANGED
@@ -2778,6 +2778,8 @@ type Shared_Type_67 = {
2778
2778
  traceQueryTimeToFirstChunk: boolean;
2779
2779
  /** Root span `name` and `spanType` in trace-scope predicates, aggregate `groupBy` and `countDistinct` */
2780
2780
  traceQueryRootSpanFields: boolean;
2781
+ /** Sorting trace and span queries by `timeToFirstChunkMs` */
2782
+ traceQueryTimeToFirstChunkSort: boolean;
2781
2783
  /** Trace query field discovery (POST /observability/traces/query/fields and /values) */
2782
2784
  traceQueryDiscovery: boolean;
2783
2785
  /** Trusted tenant scoping of trace and thread queries */
@@ -8055,7 +8057,7 @@ export type PostObservabilityTracesQuery_Body = {
8055
8057
  by: ['threadId'];
8056
8058
  } | undefined;
8057
8059
  orderBy?: {
8058
- field: 'startedAt' | 'endedAt';
8060
+ field: 'startedAt' | 'endedAt' | 'timeToFirstChunkMs';
8059
8061
  direction: 'asc' | 'desc';
8060
8062
  }[] | undefined;
8061
8063
  page?: {
@@ -8272,7 +8274,7 @@ export type PostObservabilitySpansQuery_Body = {
8272
8274
  };
8273
8275
  where?: InputShared_Auxiliary_230 | undefined;
8274
8276
  orderBy?: {
8275
- field: 'startedAt' | 'endedAt';
8277
+ field: 'startedAt' | 'endedAt' | 'timeToFirstChunkMs';
8276
8278
  direction: 'asc' | 'desc';
8277
8279
  }[];
8278
8280
  page?: {