@mastra/client-js 1.59.0-alpha.0 → 1.59.0-alpha.1

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.
@@ -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.59.0-alpha.0"
6
+ version: "1.59.0-alpha.1"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.59.0-alpha.0",
2
+ "version": "1.59.0-alpha.1",
3
3
  "package": "@mastra/client-js",
4
4
  "exports": {},
5
5
  "modules": {}
@@ -115,6 +115,8 @@ if (capabilities.spanAggregate) {
115
115
 
116
116
  The request and response structure follows `aggregateTraces()`, with direct span predicates and span dimensions such as `spanType`, `name`, and `parentEntityName`. Token and cost measures belong to the span that recorded the usage and aren't added to parent spans. Check `capabilities.spanAggregate` before calling, and `capabilities.spanAggregateModelDimensions` before grouping or counting distinct values by `model` or `provider`. With an older adapter, those requests return `501`.
117
117
 
118
+ Both `aggregateTraces()` and `aggregateSpans()` accept `timeToFirstToken.*` and `timeToFirstChunk.*` measures when `capabilities.aggregateTimeToFirstMeasures` is `true`. Spans and traces without a recorded value are skipped, never counted as 0. See [Time to first token and chunk measures](https://mastra.ai/reference/observability/tracing/advanced-queries).
119
+
118
120
  See [Aggregate spans](https://mastra.ai/reference/observability/tracing/advanced-queries) for selection, dimensions, per-span usage, and how to list the spans behind a group.
119
121
 
120
122
  ## Querying threads
@@ -44,6 +44,7 @@ The configured observability store must support each API. Call `getObservability
44
44
  | `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs` |
45
45
  | `traceQueryTimeToFirstToken` | `trace-query-time-to-first-token` | `timeToFirstTokenMs` predicates and results |
46
46
  | `traceQueryTimeToFirstTokenSort` | `trace-query-time-to-first-token-sort` | `orderBy` on `timeToFirstTokenMs` |
47
+ | `aggregateTimeToFirstMeasures` | `aggregate-time-to-first-measures` | `timeToFirstToken.*` and `timeToFirstChunk.*` measures in `aggregateTraces()` and `aggregateSpans()` |
47
48
  | `traceQueryContextIds` | `trace-query-context-ids` | `runId`, `sessionId`, `userId`, and `organizationId` predicates |
48
49
  | `traceQueryRootSpanFields` | `trace-query-root-span-fields` | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
49
50
  | `traceQueryRootEntityId` | `trace-query-root-entity-id` | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures |
@@ -811,20 +812,26 @@ Every dimension except `serviceName`, `executionSource`, and `experimentId` is a
811
812
 
812
813
  ### Measures
813
814
 
814
- | Measure | Value |
815
- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
816
- | `count` | Number of selected traces. |
817
- | `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
818
- | `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
819
- | `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
820
- | `errorCount` | Number of traces whose root span recorded an error. |
821
- | `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
822
- | `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
823
- | `tokens.output.sum`, `tokens.output.avg` | Output tokens. |
824
- | `tokens.total.sum`, `tokens.total.avg` | Input plus output tokens. |
825
- | `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
826
- | `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
827
- | `cost.sum`, `cost.avg` | Estimated model cost. |
815
+ | Measure | Value |
816
+ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
817
+ | `count` | Number of selected traces. |
818
+ | `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
819
+ | `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
820
+ | `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
821
+ | `errorCount` | Number of traces whose root span recorded an error. |
822
+ | `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
823
+ | `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
824
+ | `tokens.output.sum`, `tokens.output.avg` | Output tokens. |
825
+ | `tokens.total.sum`, `tokens.total.avg` | Input plus output tokens. |
826
+ | `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
827
+ | `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
828
+ | `cost.sum`, `cost.avg` | Estimated model cost. |
829
+ | `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
830
+ | `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
831
+ | `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
832
+ | `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
833
+ | `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
834
+ | `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
828
835
 
829
836
  Numeric measures over metadata aren't supported.
830
837
 
@@ -845,6 +852,34 @@ When you request any `cost.*` measure, every row also includes a `cost` object:
845
852
 
846
853
  `cost.sum` and `cost.avg` are `null` when the group has no priced traces or `unit` is `'mixed'`. A coverage below 1 means the cost understates the group's spend. The `cost` object isn't a measure, so `having` and `orderBy` can't reference it.
847
854
 
855
+ #### Time to first token and chunk measures
856
+
857
+ `timeToFirstToken.*` and `timeToFirstChunk.*` read the root span's `timeToFirstTokenMs` and `timeToFirstChunkMs`, the same values [`queryTraces()`](#query-traces) returns. An agent run copies them from the first model generation of its own loop:
858
+
859
+ - `timeToFirstChunk.*` is measured from the agent run's start, so it includes work done before the first model call, such as input processors and memory recall.
860
+ - `timeToFirstToken.*` is the time to first token of the model call that streamed that first chunk.
861
+
862
+ Traces without a value are skipped, never counted as 0. This includes traces whose agent run didn't stream, and traces rooted in a workflow, since a workflow run records neither value. `avg`, `min`, `max`, and the percentiles are `null` for a group where no trace has a value, and `.count` is the number of traces that do have one. Percentiles can be approximate, depending on the store.
863
+
864
+ Stores advertise support through the `aggregate-time-to-first-measures` feature, and the server reports it as the `aggregateTimeToFirstMeasures` capability. Against an older store, a request for any of these measures returns `501` before storage runs, and [field discovery](#discover-fields-and-values) omits them.
865
+
866
+ ```typescript
867
+ const { capabilities } = await mastraClient.getObservabilityCapabilities()
868
+
869
+ if (capabilities.traceAggregate && capabilities.aggregateTimeToFirstMeasures) {
870
+ const { rows } = await mastraClient.aggregateTraces({
871
+ timeRange: {
872
+ from: '2026-08-01T00:00:00.000Z',
873
+ to: '2026-08-02T00:00:00.000Z',
874
+ },
875
+ where: { op: 'eq', left: { path: 'entityType' }, right: { literal: 'agent' } },
876
+ groupBy: ['entityName'],
877
+ measures: ['timeToFirstChunk.p50', 'timeToFirstChunk.p95', 'timeToFirstChunk.count'],
878
+ orderBy: { field: 'timeToFirstChunk.p95', direction: 'desc' },
879
+ })
880
+ }
881
+ ```
882
+
848
883
  ### Filter and order groups
849
884
 
850
885
  A group is one distinct combination of `groupBy` values. `having`, `orderBy`, and `limit` operate on groups and use each group's measures over the whole time range, even when `interval` is set. The server applies `having` first, then orders the remaining groups and keeps the first `limit`. `truncated` is `true` when more groups remained than `limit`.
@@ -976,6 +1011,15 @@ Aggregation uses the same span predicates as [`querySpans()`](#query-spans), wit
976
1011
 
977
1012
  `count` counts selected spans in each group or time bucket. Buckets use each span's `startedAt`. `duration.*` measures read the span's own duration, and `errorCount` and `errorRate` read whether the span itself recorded an error.
978
1013
 
1014
+ `timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`, and skip spans without a value. Several span types record them:
1015
+
1016
+ - `model_inference`: each provider call. Filter to this type for per-call time to first token.
1017
+ - `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
1018
+ - `model_generation`: the whole generation, with the values of its first streamed inference only. A multi-step generation, such as a tool loop, reports only its first call.
1019
+ - `agent_run`: the agent run, with time to first chunk measured from the run's start. Filter to this type for latency as the caller of each agent sees it.
1020
+
1021
+ Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
1022
+
979
1023
  On ClickHouse, a direct `spanType` `eq` or `in` predicate, or one immediately inside an `and`, can select the smaller branch table. All selected types must be branch types: `agent_run`, `workflow_run`, `processor_run`, `scorer_run`, `rag_ingestion`, `tool_call`, or `mcp_tool_call`. Every requested field must be available in that table. An equivalent `or` predicate doesn't select this optimization. The branch path can differ from `querySpans()`:
980
1024
 
981
1025
  - Spans written before an upgrade from `@mastra/clickhouse` 1.4, 1.5, or 1.6 aren't in the branch table, so older windows can count fewer spans.
@@ -384,7 +384,7 @@ type InputShared_Type_13 = {
384
384
  };
385
385
  type InputShared_Type_14 = 'agent_run' | 'scorer_run' | 'classifier_evaluation' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'mcp_server_request' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping' | 'skill_resolution' | 'skill_action' | 'agent_signal';
386
386
  type InputShared_Type_15 = 'agent' | 'scorer' | 'rag_ingestion' | 'trajectory' | 'input_processor' | 'input_step_processor' | 'output_processor' | 'output_step_processor' | 'tool_result_processor' | 'workflow_step' | 'tool' | 'mcp_server' | 'workflow_run' | 'memory' | 'classifier';
387
- type InputShared_Type_16 = 'count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg';
387
+ type InputShared_Type_16 = 'count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg' | 'timeToFirstToken.avg' | 'timeToFirstToken.min' | 'timeToFirstToken.max' | 'timeToFirstToken.p50' | 'timeToFirstToken.p90' | 'timeToFirstToken.p95' | 'timeToFirstToken.p99' | 'timeToFirstToken.count' | 'timeToFirstChunk.avg' | 'timeToFirstChunk.min' | 'timeToFirstChunk.max' | 'timeToFirstChunk.p50' | 'timeToFirstChunk.p90' | 'timeToFirstChunk.p95' | 'timeToFirstChunk.p99' | 'timeToFirstChunk.count';
388
388
  type InputShared_Type_17 = {
389
389
  /** Filter by timestamp range */
390
390
  timestamp?: InputShared_Type_13 | undefined;
@@ -2857,6 +2857,8 @@ type Shared_Type_67 = {
2857
2857
  spanQueryModelFields: boolean;
2858
2858
  /** `model` and `provider` in span aggregate `groupBy` and `countDistinct`. Treat a missing value as unavailable. */
2859
2859
  spanAggregateModelDimensions: boolean;
2860
+ /** `timeToFirstToken.*` and `timeToFirstChunk.*` measures in trace and span aggregates. Treat a missing value as unavailable. */
2861
+ aggregateTimeToFirstMeasures: boolean;
2860
2862
  /** `outcome` and `stopReason` predicates in span queries and span aggregates (including `groupBy` and `countDistinct`), and `outcome`, `stopReason` and `stopReasonContext` on span rows. Treat a missing value as unavailable. */
2861
2863
  spanQueryOutcomeFields: boolean;
2862
2864
  /** The root span's `outcome` and `stopReason` in trace-scope predicates and trace aggregates, both fields in `spans.some`/`spans.none` predicates and value discovery, and the root span's `outcome`, `stopReason` and `stopReasonContext` on trace rows. Treat a missing value as unavailable. */
@@ -8280,7 +8282,7 @@ export type PostObservabilityTracesAggregate_Response = {
8280
8282
  } | undefined;
8281
8283
  bucket?: string | undefined;
8282
8284
  measures: {
8283
- [K in ('count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg') | `countDistinct.${string}`]?: number | null;
8285
+ [K in ('count' | 'duration.avg' | 'duration.min' | 'duration.max' | 'duration.p50' | 'duration.p90' | 'duration.p95' | 'duration.p99' | 'errorCount' | 'errorRate' | 'tokens.input.sum' | 'tokens.input.avg' | 'tokens.output.sum' | 'tokens.output.avg' | 'tokens.total.sum' | 'tokens.total.avg' | 'tokens.reasoning.sum' | 'tokens.reasoning.avg' | 'tokens.cached.sum' | 'tokens.cached.avg' | 'cost.sum' | 'cost.avg' | 'timeToFirstToken.avg' | 'timeToFirstToken.min' | 'timeToFirstToken.max' | 'timeToFirstToken.p50' | 'timeToFirstToken.p90' | 'timeToFirstToken.p95' | 'timeToFirstToken.p99' | 'timeToFirstToken.count' | 'timeToFirstChunk.avg' | 'timeToFirstChunk.min' | 'timeToFirstChunk.max' | 'timeToFirstChunk.p50' | 'timeToFirstChunk.p90' | 'timeToFirstChunk.p95' | 'timeToFirstChunk.p99' | 'timeToFirstChunk.count') | `countDistinct.${string}`]?: number | null;
8284
8286
  };
8285
8287
  cost?: {
8286
8288
  coverage: number | null;
@@ -8556,8 +8558,8 @@ export type PostObservabilityTracesQueryFields_Response = {
8556
8558
  }[];
8557
8559
  measures: {
8558
8560
  name: string;
8559
- kind: 'count' | 'duration' | 'error' | 'tokens' | 'cost';
8560
- statistic?: ('avg' | 'min' | 'max' | 'p50' | 'p90' | 'p95' | 'p99' | 'sum') | undefined;
8561
+ kind: 'count' | 'duration' | 'error' | 'tokens' | 'cost' | 'timeToFirstToken' | 'timeToFirstChunk';
8562
+ statistic?: ('avg' | 'min' | 'max' | 'p50' | 'p90' | 'p95' | 'p99' | 'sum' | 'count') | undefined;
8561
8563
  unit: 'count' | 'milliseconds' | 'ratio' | 'tokens' | 'currency';
8562
8564
  approximate: boolean;
8563
8565
  }[];