@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.
- package/dist/client.d.ts +5 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/docs/SKILL.md +5 -5
- package/dist/docs/assets/SOURCE_MAP.json +6 -6
- package/dist/docs/references/docs-harness-schedules.md +2 -0
- package/dist/docs/references/docs-signals-sending-signals.md +3 -1
- package/dist/docs/references/integrations-auth-clerk.md +46 -7
- package/dist/docs/references/integrations-auth-neon.md +217 -0
- package/dist/docs/references/integrations-auth-supabase.md +46 -7
- package/dist/docs/references/integrations-auth-workos.md +54 -15
- package/dist/docs/references/reference-client-js-agents.md +4 -4
- package/dist/docs/references/reference-client-js-observability.md +23 -1
- package/dist/docs/references/reference-observability-tracing-advanced-queries.md +47 -58
- package/dist/index.cjs +32 -9
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +32 -9
- package/dist/index.js.map +1 -1
- package/dist/resources/agent.d.ts +16 -9
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/resources/observability.d.ts +5 -1
- package/dist/resources/observability.d.ts.map +1 -1
- package/dist/route-types.generated.d.ts +235 -211
- package/dist/route-types.generated.d.ts.map +1 -1
- package/dist/types.d.ts +3 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
- package/dist/docs/references/reference-migrations-upgrade-to-v1-client.md +0 -341
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
94
|
+
### Usage examples
|
|
56
95
|
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
125
|
+
### Configuration
|
|
87
126
|
|
|
88
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
####
|
|
917
|
+
#### Resumable streams for stored agents
|
|
918
918
|
|
|
919
|
-
Set `durable` to
|
|
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: {
|
|
930
|
+
durable: { cleanupTimeoutMs: 0 },
|
|
931
931
|
})
|
|
932
932
|
```
|
|
933
933
|
|
|
934
|
-
Only serializable options are accepted
|
|
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
|
|
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`
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 -
|
|
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
|
-
*
|
|
3256
|
-
*
|
|
3257
|
-
*
|
|
3258
|
-
*
|
|
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
|
|
3262
|
-
*
|
|
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);
|