@mastra/client-js 1.60.0-alpha.0 → 1.60.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.
@@ -4,9 +4,48 @@
4
4
 
5
5
  # Supabase
6
6
 
7
+ Use Supabase with Mastra in two ways:
8
+
9
+ - **Agent tools** let an agent query tables, call database functions, and manage storage and auth users in Supabase through [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect).
10
+ - **[Server authentication](#server-authentication)** verifies requests to your Mastra server with Supabase, using the `@mastra/auth-supabase` package.
11
+
12
+ ## Connect
13
+
14
+ Before you start, complete the [Connect setup](https://mastra.ai/docs/mastra-platform/connect) to install `@mastra/connect` and configure your platform project.
15
+
16
+ ### Agent tools
17
+
18
+ Give agents tools to query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.
19
+
20
+ Connect an account with the `supabase` provider ID. Run this command from the directory that contains your `.env` file:
21
+
22
+ ```bash
23
+ mastra connect add supabase
24
+ ```
25
+
26
+ Then pass [`tools()`](https://mastra.ai/reference/connect/tools) to the agent and select the provider:
27
+
28
+ ```typescript
29
+ import { Agent } from '@mastra/core/agent'
30
+ import { tools } from '@mastra/connect'
31
+
32
+ export const supabaseAgent = new Agent({
33
+ id: 'supabase-agent',
34
+ name: 'Supabase agent',
35
+ instructions:
36
+ 'You help people query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.',
37
+ model: '__GATEWAY_OPENAI_MODEL_LUNA__',
38
+ tools: tools({ providers: ['supabase'] }),
39
+ })
40
+ ```
41
+
42
+ The agent gets 27 Supabase tools, with keys such as `supabase_copy_storage_object`. See [Supabase tools](https://mastra.ai/reference/connect/providers) for the full list, and the [`tools()` parameters](https://mastra.ai/reference/connect/tools) to restrict tools or require approval before a call runs.
43
+
44
+ ## Server authentication
45
+
7
46
  The `@mastra/auth-supabase` package provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
8
47
 
9
- ## Prerequisites
48
+ ### Prerequisites
10
49
 
11
50
  This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
12
51
 
@@ -17,7 +56,7 @@ SUPABASE_ANON_KEY=your-anon-key
17
56
 
18
57
  > **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
19
58
 
20
- ## Installation
59
+ ### Installation
21
60
 
22
61
  Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
23
62
 
@@ -45,7 +84,7 @@ yarn add @mastra/auth-supabase@latest
45
84
  bun add @mastra/auth-supabase@latest
46
85
  ```
47
86
 
48
- ## Usage example
87
+ ### Usage example
49
88
 
50
89
  ```typescript
51
90
  import { Mastra } from '@mastra/core'
@@ -65,11 +104,11 @@ export const mastra = new Mastra({
65
104
  >
66
105
  > Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
67
106
 
68
- ## Client-side setup
107
+ ### Client-side setup
69
108
 
70
109
  When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
71
110
 
72
- ### Retrieving the access token
111
+ #### Retrieving the access token
73
112
 
74
113
  Use the Supabase client to authenticate users and retrieve their access token:
75
114
 
@@ -88,7 +127,7 @@ const accessToken = authTokenResponse.data?.session?.access_token
88
127
 
89
128
  > **Note:** Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
90
129
 
91
- ## Configuring `MastraClient`
130
+ ### Configuring `MastraClient`
92
131
 
93
132
  When `auth` is enabled, all requests made with `MastraClient` must include a valid Supabase access token in the `Authorization` header:
94
133
 
@@ -107,7 +146,7 @@ export const mastraClient = new MastraClient({
107
146
  >
108
147
  > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
109
148
 
110
- ### Making authenticated requests
149
+ #### Making authenticated requests
111
150
 
112
151
  Once `MastraClient` is configured with the Supabase access token, you can send authenticated requests:
113
152
 
@@ -4,9 +4,48 @@
4
4
 
5
5
  # WorkOS
6
6
 
7
+ Use WorkOS with Mastra in two ways:
8
+
9
+ - **Agent tools** let an agent manage WorkOS organizations, users, and SSO connections through [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect).
10
+ - **[Server authentication](#server-authentication)** verifies requests to your Mastra server with WorkOS, using the `@mastra/auth-workos` package.
11
+
12
+ ## Connect
13
+
14
+ Before you start, complete the [Connect setup](https://mastra.ai/docs/mastra-platform/connect) to install `@mastra/connect` and configure your platform project.
15
+
16
+ ### Agent tools
17
+
18
+ Give agents tools to manage organizations, users, memberships, invitations, SSO connections, and directories in WorkOS.
19
+
20
+ Connect an account with the `workos` provider ID. Run this command from the directory that contains your `.env` file:
21
+
22
+ ```bash
23
+ mastra connect add workos
24
+ ```
25
+
26
+ Then pass [`tools()`](https://mastra.ai/reference/connect/tools) to the agent and select the provider:
27
+
28
+ ```typescript
29
+ import { Agent } from '@mastra/core/agent'
30
+ import { tools } from '@mastra/connect'
31
+
32
+ export const workosAgent = new Agent({
33
+ id: 'workos-agent',
34
+ name: 'WorkOS agent',
35
+ instructions:
36
+ 'You help people manage organizations, users, memberships, invitations, SSO connections, and directories in WorkOS.',
37
+ model: '__GATEWAY_OPENAI_MODEL_LUNA__',
38
+ tools: tools({ providers: ['workos'] }),
39
+ })
40
+ ```
41
+
42
+ The agent gets 40 WorkOS tools, with keys such as `workos_create_connection`. See [WorkOS tools](https://mastra.ai/reference/connect/providers) for the full list, and the [`tools()` parameters](https://mastra.ai/reference/connect/tools) to restrict tools or require approval before a call runs.
43
+
44
+ ## Server authentication
45
+
7
46
  The `@mastra/auth-workos` package provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
8
47
 
9
- ## Prerequisites
48
+ ### Prerequisites
10
49
 
11
50
  This example uses WorkOS authentication. Make sure to:
12
51
 
@@ -24,7 +63,7 @@ WORKOS_CLIENT_ID=client_...
24
63
  >
25
64
  > For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
26
65
 
27
- ## Installation
66
+ ### Installation
28
67
 
29
68
  Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
30
69
 
@@ -52,9 +91,9 @@ yarn add @mastra/auth-workos@latest
52
91
  bun add @mastra/auth-workos@latest
53
92
  ```
54
93
 
55
- ## Usage examples
94
+ ### Usage examples
56
95
 
57
- ### Basic usage with environment variables
96
+ #### Basic usage with environment variables
58
97
 
59
98
  ```typescript
60
99
  import { Mastra } from '@mastra/core'
@@ -67,7 +106,7 @@ export const mastra = new Mastra({
67
106
  })
68
107
  ```
69
108
 
70
- ### Custom configuration
109
+ #### Custom configuration
71
110
 
72
111
  ```typescript
73
112
  import { Mastra } from '@mastra/core'
@@ -83,13 +122,13 @@ export const mastra = new Mastra({
83
122
  })
84
123
  ```
85
124
 
86
- ## Configuration
125
+ ### Configuration
87
126
 
88
- ### Default authorization
127
+ #### Default authorization
89
128
 
90
129
  By default, `MastraAuthWorkos` grants access to any authenticated WorkOS user. The authorization check succeeds when the resolved user object contains both a Mastra user ID and a WorkOS user ID.
91
130
 
92
- ### FGA membership loading
131
+ #### FGA membership loading
93
132
 
94
133
  > **Note:** FGA requires a Mastra Enterprise Edition (EE) license in production. It works without a license in development. See [what requires an EE license](https://mastra.ai/docs/license). [Contact sales](https://mastra.ai/contact) for more information.
95
134
 
@@ -112,7 +151,7 @@ const workosFga = new MastraFGAWorkos({
112
151
 
113
152
  When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
114
153
 
115
- ### Service tokens and custom JWT templates
154
+ #### Service tokens and custom JWT templates
116
155
 
117
156
  For machine-to-machine or service-account access, you can configure `MastraAuthWorkos` to trust verified bearer-token claims from a WorkOS custom JWT template.
118
157
 
@@ -133,7 +172,7 @@ const workosAuth = new MastraAuthWorkos({
133
172
 
134
173
  This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token isn't meant to round-trip through `workos.userManagement.getUser()`.
135
174
 
136
- ### Custom authorization
175
+ #### Custom authorization
137
176
 
138
177
  If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
139
178
 
@@ -155,11 +194,11 @@ const workosAuth = new AdminOnlyWorkosAuth({
155
194
 
156
195
  Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
157
196
 
158
- ## Client-side setup
197
+ ### Client-side setup
159
198
 
160
199
  When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
161
200
 
162
- ### Installing WorkOS SDK
201
+ #### Installing WorkOS SDK
163
202
 
164
203
  First, install the WorkOS SDK in your application:
165
204
 
@@ -187,7 +226,7 @@ yarn add @workos-inc/node
187
226
  bun add @workos-inc/node
188
227
  ```
189
228
 
190
- ### Exchanging code for access token
229
+ #### Exchanging code for access token
191
230
 
192
231
  After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
193
232
 
@@ -208,7 +247,7 @@ export const authenticateWithWorkos = async (code: string, clientId: string) =>
208
247
 
209
248
  > **Note:** Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
210
249
 
211
- ## Configuring `MastraClient`
250
+ ### Configuring `MastraClient`
212
251
 
213
252
  When `auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
214
253
 
@@ -229,7 +268,7 @@ export const createMastraClient = (accessToken: string) => {
229
268
  >
230
269
  > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
231
270
 
232
- ### Making authenticated requests
271
+ #### Making authenticated requests
233
272
 
234
273
  Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
235
274
 
@@ -914,9 +914,9 @@ const agent = await mastraClient.createStoredAgent({
914
914
  })
915
915
  ```
916
916
 
917
- #### Durable stored agents
917
+ #### Resumable streams for stored agents
918
918
 
919
- Set `durable` to run the agent as a [durable agent](https://mastra.ai/docs/harness/durable-agents) once the server hydrates it. Pass `true` to accept the defaults, or an object to tune the durable loop:
919
+ Set `durable` to configure [resumable streams](https://mastra.ai/docs/agents/resumable-streams) on the hydrated plain agent. Pass `true` to enable streams, `false` to disable them, or an object to tune stream cleanup:
920
920
 
921
921
  ```typescript
922
922
  const agent = await mastraClient.createStoredAgent({
@@ -927,11 +927,11 @@ const agent = await mastraClient.createStoredAgent({
927
927
  provider: 'openai',
928
928
  name: 'gpt-5.4',
929
929
  },
930
- durable: { maxSteps: 50, cleanupTimeoutMs: 0 },
930
+ durable: { cleanupTimeoutMs: 0 },
931
931
  })
932
932
  ```
933
933
 
934
- Only serializable options are accepted. The durable cache and pubsub are inherited from the server's `Mastra` instance. If it has no distributed cache or pubsub configured, durability is process-local. Automatic recovery is still configured in code through `recovery.durableAgents`.
934
+ Only serializable options are accepted, with cache and pubsub inherited from the server's `Mastra` instance. Existing stored agents with `durable: true` also use this field for resumable streams only. To retain durable execution and checkpoint recovery, register a code agent wrapped with `createDurableAgent({ agent })`.
935
935
 
936
936
  ### `getStoredAgent()`
937
937
 
@@ -115,7 +115,7 @@ 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).
118
+ Both `aggregateTraces()` and `aggregateSpans()` accept time to first token (TTFT) and time to first chunk (TTFC) measures, `timeToFirstToken.*` and `timeToFirstChunk.*`, when `capabilities.aggregateTimeToFirstMeasures` is `true`. Spans and traces without a recorded value are skipped, never counted as 0. See [Time to first chunk (TTFC)](https://mastra.ai/reference/observability/tracing/advanced-queries) and [Time to first token (TTFT)](https://mastra.ai/reference/observability/tracing/advanced-queries).
119
119
 
120
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.
121
121
 
@@ -403,6 +403,16 @@ const scores = await mastraClient.listScoresBySpan({
403
403
  })
404
404
  ```
405
405
 
406
+ ## Get a score by ID
407
+
408
+ Use `getScore()` to retrieve one observability score:
409
+
410
+ ```typescript
411
+ const { score } = await mastraClient.getScore('score-id-123')
412
+ ```
413
+
414
+ The response is `{ score: record | null }`. A missing score returns HTTP 200 with `{ score: null }`. The return type is `GetScoreResponse`, exported from `@mastra/client-js`.
415
+
406
416
  ## Creating scores
407
417
 
408
418
  Create a score for a trace, optionally identifying a span within it:
@@ -424,6 +434,18 @@ const response = await mastraClient.createScore({
424
434
 
425
435
  Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the configured API server. Create methods support OSS and Platform. Full replacement uses Platform's PUT endpoint. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
426
436
 
437
+ ### Get feedback by ID
438
+
439
+ Use `getFeedback()` to retrieve one feedback record:
440
+
441
+ ```typescript
442
+ const { feedback } = await mastraClient.getFeedback('feedback-id-123')
443
+ ```
444
+
445
+ The response is `{ feedback: record | null }`. A missing record returns HTTP 200 with `{ feedback: null }`. The return type is `GetFeedbackResponse`, exported from `@mastra/client-js`.
446
+
447
+ Both getters accept an unencoded ID and encode it as a URL path segment. They use the client's configured API prefix, credentials, and headers. Record timestamps are ISO strings in the JSON response.
448
+
427
449
  ### Creating feedback
428
450
 
429
451
  Create a feedback record for a trace, optionally identifying a span within it:
@@ -128,39 +128,9 @@ This top-level predicate doesn't inspect child spans. In contrast, `spans.some`
128
128
 
129
129
  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`.
130
130
 
131
- #### Filter by time to first chunk
131
+ #### Filter and sort by time to first chunk or token
132
132
 
133
- `timeToFirstChunkMs` is the time in milliseconds from a span's start to the first chunk of its model response. Agent run and model spans record it when the model streams a response. At trace scope, the field reads the current root span's value. Inside `spans.some` or `spans.none`, it reads each related span.
134
-
135
- This predicate finds traces with a model call that took more than 2 seconds to stream its first chunk:
136
-
137
- ```typescript
138
- const slowFirstChunk = {
139
- spans: {
140
- some: {
141
- op: 'and',
142
- args: [
143
- { op: 'eq', left: { path: 'spanType' }, right: { literal: 'model_generation' } },
144
- { op: 'gt', left: { path: 'timeToFirstChunkMs' }, right: { literal: 2000 } },
145
- ],
146
- },
147
- },
148
- }
149
- ```
150
-
151
- 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.
152
-
153
- 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.
154
-
155
- #### Sort by time to first chunk
156
-
157
- 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()`.
158
-
159
- 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.
160
-
161
- #### Filter and sort by time to first token
162
-
163
- `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.
133
+ `timeToFirstChunkMs` holds a span's [time to first chunk (TTFC)](#time-to-first-chunk-ttfc), and `timeToFirstTokenMs` holds its [time to first token (TTFT)](#time-to-first-token-ttft). At trace scope, the fields read the root span's value. Inside `spans.some` or `spans.none`, they read each related span. Both fields also work in `orderBy`.
164
134
 
165
135
  This predicate finds traces whose root agent waited more than 2 seconds for the model's first token:
166
136
 
@@ -168,9 +138,7 @@ This predicate finds traces whose root agent waited more than 2 seconds for the
168
138
  const slowFirstToken = { op: 'gt', left: { path: 'timeToFirstTokenMs' }, right: { literal: 2000 } }
169
139
  ```
170
140
 
171
- `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.
172
-
173
- 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.
141
+ See [Missing first chunk and token values](#missing-first-chunk-and-token-values) for `null`, `0`, and the capabilities each use needs.
174
142
 
175
143
  #### Filter by outcome
176
144
 
@@ -570,7 +538,7 @@ A query using keyset pagination returns lightweight completed traces and a curso
570
538
 
571
539
  The response includes `name`, `createdAt`, identity fields, `metadata`, and input/output/error previews. Supported nullable fields remain present with `null` when no value was recorded. Fields that require an optional store feature are omitted when the store lacks that feature. Previews summarize payloads; retrieve the full trace for complete input, output, and error details.
572
540
 
573
- `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). `outcome`, `stopReason`, and `stopReasonContext` read the root span and are present only when the store supports the `traceQueryOutcomeFields` capability. They're `null` when the root span didn't record them. See [Filter by outcome](#filter-by-outcome).
541
+ `timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token). `outcome`, `stopReason`, and `stopReasonContext` read the root span and are present only when the store supports the `traceQueryOutcomeFields` capability. They're `null` when the root span didn't record them. See [Filter by outcome](#filter-by-outcome).
574
542
 
575
543
  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.
576
544
 
@@ -838,6 +806,12 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
838
806
  | `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
839
807
  | `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
840
808
  | `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
809
+ | `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
810
+ | `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
811
+ | `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
812
+ | `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
813
+ | `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
814
+ | `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
841
815
  | `errorCount` | Number of traces whose root span recorded an error. |
842
816
  | `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
843
817
  | `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
@@ -846,12 +820,6 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
846
820
  | `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
847
821
  | `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
848
822
  | `cost.sum`, `cost.avg` | Estimated model cost. |
849
- | `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
850
- | `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
851
- | `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
852
- | `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
853
- | `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
854
- | `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
855
823
 
856
824
  Numeric measures over metadata aren't supported.
857
825
 
@@ -872,16 +840,11 @@ When you request any `cost.*` measure, every row also includes a `cost` object:
872
840
 
873
841
  `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.
874
842
 
875
- #### Time to first token and chunk measures
876
-
877
- `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:
878
-
879
- - `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.
880
- - `timeToFirstToken.*` is the time to first token of the model call that streamed that first chunk.
843
+ ### Time to first chunk (TTFC)
881
844
 
882
- 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.
845
+ Time to first chunk (TTFC) is how long a caller waits for the first streamed chunk. `timeToFirstChunkMs` is the time from a span's start to the first chunk of its model response. Agent run and model spans record it when the model streams a response. On an agent run, it's measured from the run's start and includes work done before the first model call, such as input processors and memory recall.
883
846
 
884
- 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.
847
+ The `timeToFirstChunk.*` measures aggregate the root span's `timeToFirstChunkMs`, the same value [`queryTraces()`](#query-traces) returns. To filter or sort by it, see [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token).
885
848
 
886
849
  ```typescript
887
850
  const { capabilities } = await mastraClient.getObservabilityCapabilities()
@@ -900,6 +863,39 @@ if (capabilities.traceAggregate && capabilities.aggregateTimeToFirstMeasures) {
900
863
  }
901
864
  ```
902
865
 
866
+ ### Time to first token (TTFT)
867
+
868
+ Time to first token (TTFT) is the time in milliseconds from the start of a model call, the provider request itself, to the first chunk that call streams. Unlike TTFC, it leaves out the work Mastra does before calling the model, such as input processors.
869
+
870
+ The `timeToFirstToken.*` measures aggregate the root span's `timeToFirstTokenMs`. To filter or sort by it, see [Filter and sort by time to first chunk or token](#filter-and-sort-by-time-to-first-chunk-or-token). Compare TTFC with TTFT to see how much of an agent's wait comes from work before the model call.
871
+
872
+ ### First chunk and token span types
873
+
874
+ These span types record TTFC and TTFT:
875
+
876
+ - `model_inference`: each provider call.
877
+ - `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
878
+ - `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.
879
+ - `agent_run`: the agent run, with the values of the first model generation of its own loop. Its TTFC is measured from the run's start.
880
+
881
+ Other spans, such as tool calls and workflow runs, record neither value. A trace rooted in a workflow has no TTFC or TTFT at trace scope.
882
+
883
+ TTFT is measured once, on the `model_inference` span that streamed the chunk. A step with a fallback model or a retry takes the value of its first inference that streamed a chunk. A failed fallback attempt has a value only if it streamed a chunk before failing. An in-process agent retries a failed model call inside a single inference span. Its TTFT then includes the failed attempt and the retry wait. Durable agents open one inference span per attempt.
884
+
885
+ Mastra storage keeps TTFT in its own column, not in the stored `attributes`. Read it from the span's `timeToFirstTokenMs` field.
886
+
887
+ ### Missing first chunk and token values
888
+
889
+ The value is `null` when the span didn't stream a chunk. A value of `0` isn't missing. It means the first chunk arrived in the same millisecond the span started.
890
+
891
+ - In predicates, `null` counts as missing. It matches `notExists` and never matches ordered predicates.
892
+ - In `orderBy`, missing values sort last in both directions, and `0` sorts as a value.
893
+ - In aggregates, spans and traces without a value are skipped, never counted as 0.
894
+
895
+ Filtering, sorting, and aggregating each require a store feature. See [Check capabilities](#check-capabilities) for the `traceQueryTimeToFirstChunk`, `traceQueryTimeToFirstChunkSort`, `traceQueryTimeToFirstToken`, `traceQueryTimeToFirstTokenSort`, and `aggregateTimeToFirstMeasures` flags. Against an older store, results omit the unsupported fields, a request that uses them returns `501` before storage runs, and [field discovery](#discover-fields-and-values) omits them.
896
+
897
+ For `timeToFirstChunk.*` and `timeToFirstToken.*`, `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. The measures require the `aggregateTimeToFirstMeasures` capability.
898
+
903
899
  ### Filter and order groups
904
900
 
905
901
  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`.
@@ -1031,14 +1027,7 @@ Aggregation uses the same span predicates as [`querySpans()`](#query-spans), wit
1031
1027
 
1032
1028
  `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.
1033
1029
 
1034
- `timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`, and skip spans without a value. Several span types record them:
1035
-
1036
- - `model_inference`: each provider call. Filter to this type for per-call time to first token.
1037
- - `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
1038
- - `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.
1039
- - `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.
1040
-
1041
- Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
1030
+ `timeToFirstToken.*` and `timeToFirstChunk.*` read the span's own `timeToFirstTokenMs` and `timeToFirstChunkMs`. See [First chunk and token span types](#first-chunk-and-token-span-types) for which spans record them. Filter to `model_inference` for per-call TTFT, or to `agent_run` for latency as the caller of each agent sees it. Without a `spanType` filter, one agent call contributes its agent run, its model generation, and every model step and model inference.
1042
1031
 
1043
1032
  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()`:
1044
1033
 
package/dist/index.cjs CHANGED
@@ -3247,20 +3247,27 @@ var Agent = class extends BaseResource {
3247
3247
  * Use this to resume receiving events after a disconnection.
3248
3248
  *
3249
3249
  * @param params.runId - The run ID to observe
3250
- * @param params.offset - Optional position to resume from (0-based). If omitted, replays all events.
3250
+ * @param params.offset - Run-log position to resume from. Chunks from `observe()`, and from `stream()` on
3251
+ * durable and evented agents, carry an `index`; pass the `index + 1` of the last chunk that has one. Chunks without an `index`
3252
+ * (`abort` and structured-output `object` chunks) are skipped when choosing the offset. If omitted,
3253
+ * replays the chunks still cached for the run, or only live chunks if the server's transport can't replay.
3251
3254
  * @returns Promise containing a streaming Response
3252
3255
  *
3253
3256
  * @example
3254
3257
  * ```typescript
3255
- * // Reconnect to a stream from a specific position
3256
- * const response = await client.agents('my-agent').observe({
3257
- * runId: 'run-123',
3258
- * offset: 42, // Resume from event 42
3259
- * });
3258
+ * const agent = client.getAgent('my-agent');
3259
+ * let offset = 0;
3260
+ * const trackOffset = async (chunk: { index?: number }) => {
3261
+ * if (chunk.index === undefined) return;
3262
+ * offset = chunk.index + 1;
3263
+ * };
3260
3264
  *
3261
- * await response.processDataStream({
3262
- * onChunk: (chunk) => console.log('Received:', chunk),
3263
- * });
3265
+ * const stream = await agent.stream(messages, { runId: 'run-123' });
3266
+ * await stream.processDataStream({ onChunk: trackOffset });
3267
+ *
3268
+ * // After a dropped connection, resume where the last indexed chunk left off
3269
+ * const response = await agent.observe({ runId: 'run-123', offset });
3270
+ * await response.processDataStream({ onChunk: trackOffset });
3264
3271
  * ```
3265
3272
  */
3266
3273
  async observe(params) {
@@ -5664,6 +5671,10 @@ var Observability = class extends BaseResource {
5664
5671
  ]);
5665
5672
  return this.request(`/observability/logs${queryString ? `?${queryString}` : ""}`);
5666
5673
  }
5674
+ /** Retrieves one score by ID; the response contains null when it is missing. */
5675
+ getScore(id) {
5676
+ return this.request(`/observability/scores/${encodeURIComponent(id)}`);
5677
+ }
5667
5678
  /**
5668
5679
  * Retrieves a paginated list of scores with optional filtering and sorting.
5669
5680
  */
@@ -5737,6 +5748,10 @@ var Observability = class extends BaseResource {
5737
5748
  body: params
5738
5749
  });
5739
5750
  }
5751
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
5752
+ getFeedback(id) {
5753
+ return this.request(`/observability/feedback/${encodeURIComponent(id)}`);
5754
+ }
5740
5755
  /**
5741
5756
  * Retrieves a paginated list of feedback with optional filtering and sorting.
5742
5757
  */
@@ -8524,6 +8539,10 @@ var MastraClient = class extends BaseResource {
8524
8539
  listLogsVNext(params = {}) {
8525
8540
  return this.observability.listLogs(params);
8526
8541
  }
8542
+ /** Retrieves one score by ID; the response contains null when it is missing. */
8543
+ getScore(id) {
8544
+ return this.observability.getScore(id);
8545
+ }
8527
8546
  /** Retrieves a paginated list of observability scores. */
8528
8547
  listScores(params = {}) {
8529
8548
  return this.observability.listScores(params);
@@ -8552,6 +8571,10 @@ var MastraClient = class extends BaseResource {
8552
8571
  getScorePercentiles(params) {
8553
8572
  return this.observability.getScorePercentiles(params);
8554
8573
  }
8574
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
8575
+ getFeedback(id) {
8576
+ return this.observability.getFeedback(id);
8577
+ }
8555
8578
  /** Retrieves a paginated list of feedback records. */
8556
8579
  listFeedback(params = {}) {
8557
8580
  return this.observability.listFeedback(params);