@mastra/client-js 1.60.0-alpha.0 → 1.60.0-alpha.10
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 +15 -4
- 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 +3 -1
- 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 +36 -6
- package/dist/docs/references/reference-observability-tracing-advanced-queries.md +49 -59
- package/dist/index.cjs +87 -39
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +87 -39
- package/dist/index.js.map +1 -1
- package/dist/resources/agent.d.ts +18 -11
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/resources/observability-route-types.d.ts +8 -10
- package/dist/resources/observability-route-types.d.ts.map +1 -1
- package/dist/resources/observability.d.ts +12 -2
- package/dist/resources/observability.d.ts.map +1 -1
- package/dist/route-types.generated.d.ts +343 -212
- package/dist/route-types.generated.d.ts.map +1 -1
- package/dist/types.d.ts +5 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
- 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
|
|
|
@@ -371,11 +371,17 @@ const result = await mastraClient.deleteTraces({
|
|
|
371
371
|
traceIds: ['trace-1', 'trace-2'],
|
|
372
372
|
})
|
|
373
373
|
|
|
374
|
-
|
|
374
|
+
if ('accepted' in result) {
|
|
375
|
+
console.log('Deletion requested')
|
|
376
|
+
} else {
|
|
377
|
+
console.log(result.success)
|
|
378
|
+
}
|
|
375
379
|
```
|
|
376
380
|
|
|
377
381
|
Each request accepts up to 1,000 trace IDs and no tenant scope fields. Signals that aren't linked to a trace are preserved. Traces created by experiments are deleted like any other trace.
|
|
378
382
|
|
|
383
|
+
The client supports two response shapes: OSS returns `{ success: true }` after its delete operation, while a Platform backend that supports queued batch deletion returns `202 { accepted: true }` after accepting cleanup. Acceptance doesn't mean records have disappeared from reads, so check the response before reporting deletion as complete. Using these client methods with Platform requires a deployment that supports the batch deletion endpoints.
|
|
384
|
+
|
|
379
385
|
## Scoring traces
|
|
380
386
|
|
|
381
387
|
Score specific traces using registered scorers for evaluation:
|
|
@@ -403,6 +409,16 @@ const scores = await mastraClient.listScoresBySpan({
|
|
|
403
409
|
})
|
|
404
410
|
```
|
|
405
411
|
|
|
412
|
+
## Get a score by ID
|
|
413
|
+
|
|
414
|
+
Use `getScore()` to retrieve one observability score:
|
|
415
|
+
|
|
416
|
+
```typescript
|
|
417
|
+
const { score } = await mastraClient.getScore('score-id-123')
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
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`.
|
|
421
|
+
|
|
406
422
|
## Creating scores
|
|
407
423
|
|
|
408
424
|
Create a score for a trace, optionally identifying a span within it:
|
|
@@ -422,7 +438,19 @@ const response = await mastraClient.createScore({
|
|
|
422
438
|
|
|
423
439
|
## Feedback
|
|
424
440
|
|
|
425
|
-
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
|
|
441
|
+
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 is supported by Platform and OSS servers with feedback replacement support. 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.
|
|
442
|
+
|
|
443
|
+
### Get feedback by ID
|
|
444
|
+
|
|
445
|
+
Use `getFeedback()` to retrieve one feedback record:
|
|
446
|
+
|
|
447
|
+
```typescript
|
|
448
|
+
const { feedback } = await mastraClient.getFeedback('feedback-id-123')
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
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`.
|
|
452
|
+
|
|
453
|
+
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.
|
|
426
454
|
|
|
427
455
|
### Creating feedback
|
|
428
456
|
|
|
@@ -470,9 +498,9 @@ Create responses contain `success` and optional `data` with the generated or sup
|
|
|
470
498
|
|
|
471
499
|
Explicit modes require server support. Older servers may ignore `contextMode`. Deploy Platform's supplied-context support before sending `"provided"` there.
|
|
472
500
|
|
|
473
|
-
### Replacing feedback
|
|
501
|
+
### Replacing feedback
|
|
474
502
|
|
|
475
|
-
`replaceFeedback()` sends a full replacement to `PUT /api/observability/feedback/:feedbackId`. Include the original `feedbackId`, `traceId`, and normalized `timestamp`, along with all feedback fields to retain.
|
|
503
|
+
`replaceFeedback()` sends a full replacement to `PUT /api/observability/feedback/:feedbackId`. Include the original `feedbackId`, `traceId`, and normalized `timestamp`, along with all feedback fields to retain. Platform and OSS servers with feedback replacement support accept this method. OSS returns `501` when its storage adapter doesn't support replacement. For OSS, check `capabilities.feedbackReplacement` before offering edits. A missing capability means unavailable.
|
|
476
504
|
|
|
477
505
|
```typescript
|
|
478
506
|
await mastraClient.replaceFeedback({
|
|
@@ -487,7 +515,7 @@ await mastraClient.replaceFeedback({
|
|
|
487
515
|
})
|
|
488
516
|
```
|
|
489
517
|
|
|
490
|
-
Use the normalized timestamp from the create response's `data` when available.
|
|
518
|
+
Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable automatic retries.
|
|
491
519
|
|
|
492
520
|
### Deleting feedback and scores
|
|
493
521
|
|
|
@@ -507,6 +535,8 @@ await mastraClient.deleteScores({
|
|
|
507
535
|
})
|
|
508
536
|
```
|
|
509
537
|
|
|
538
|
+
Both methods return `{ success: boolean }` from OSS or `{ accepted: true }` from a Platform backend that supports queued batch deletion. See [Deleting traces](#deleting-traces) for response handling. Accepted records can remain readable until cleanup runs. Platform uses authenticated organization/project scope, which request-body scope fields can't override.
|
|
539
|
+
|
|
510
540
|
### Listing feedback
|
|
511
541
|
|
|
512
542
|
Retrieve paginated feedback records with optional filters:
|
|
@@ -35,6 +35,7 @@ The configured observability store must support each API. Call `getObservability
|
|
|
35
35
|
| -------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
36
36
|
| `traceQuery` | `trace-query` | `queryTraces()` |
|
|
37
37
|
| `spanQuery` | `span-query` | `querySpans()` |
|
|
38
|
+
| `spanQueryDurationSort` | `span-query-duration-sort` | `orderBy` on `durationMs` in `querySpans()` |
|
|
38
39
|
| `spanQueryContextFields` | `span-query-context-fields` | Additional identity, context, and parent/root entity predicates in span queries and aggregates |
|
|
39
40
|
| `spanQueryModelFields` | `span-query-model-fields` | `model` and `provider` predicates in span queries and aggregates |
|
|
40
41
|
| `traceAggregate` | `trace-aggregate` | `aggregateTraces()` |
|
|
@@ -128,39 +129,9 @@ This top-level predicate doesn't inspect child spans. In contrast, `spans.some`
|
|
|
128
129
|
|
|
129
130
|
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
131
|
|
|
131
|
-
#### Filter by time to first chunk
|
|
132
|
+
#### Filter and sort by time to first chunk or token
|
|
132
133
|
|
|
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.
|
|
134
|
+
`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
135
|
|
|
165
136
|
This predicate finds traces whose root agent waited more than 2 seconds for the model's first token:
|
|
166
137
|
|
|
@@ -168,9 +139,7 @@ This predicate finds traces whose root agent waited more than 2 seconds for the
|
|
|
168
139
|
const slowFirstToken = { op: 'gt', left: { path: 'timeToFirstTokenMs' }, right: { literal: 2000 } }
|
|
169
140
|
```
|
|
170
141
|
|
|
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.
|
|
142
|
+
See [Missing first chunk and token values](#missing-first-chunk-and-token-values) for `null`, `0`, and the capabilities each use needs.
|
|
174
143
|
|
|
175
144
|
#### Filter by outcome
|
|
176
145
|
|
|
@@ -570,7 +539,7 @@ A query using keyset pagination returns lightweight completed traces and a curso
|
|
|
570
539
|
|
|
571
540
|
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
541
|
|
|
573
|
-
`timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter
|
|
542
|
+
`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
543
|
|
|
575
544
|
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
545
|
|
|
@@ -704,7 +673,7 @@ const result = await mastraClient.querySpans({
|
|
|
704
673
|
console.log(result.spans)
|
|
705
674
|
```
|
|
706
675
|
|
|
707
|
-
Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, ascending or descending, and defaults to descending start time. Spans without a value for the `timeToFirstChunkMs` or `timeToFirstTokenMs` sort field sort last in both directions.
|
|
676
|
+
Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, ascending or descending, and defaults to descending start time. Spans without a value for the `timeToFirstChunkMs` or `timeToFirstTokenMs` sort field sort last in both directions.
|
|
708
677
|
|
|
709
678
|
| Fields | Operators |
|
|
710
679
|
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
@@ -838,6 +807,12 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
|
|
|
838
807
|
| `countDistinct.<field>` | Number of distinct non-null values of a dimension or `traceId`, such as `countDistinct.userId`. |
|
|
839
808
|
| `duration.avg`, `duration.min`, `duration.max` | Root span duration in milliseconds. |
|
|
840
809
|
| `duration.p50`, `duration.p90`, `duration.p95`, `duration.p99` | Root span duration percentile in milliseconds. Percentiles can be approximate, depending on the store. |
|
|
810
|
+
| `timeToFirstChunk.avg`, `timeToFirstChunk.min`, `timeToFirstChunk.max` | Root span time to first chunk in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
811
|
+
| `timeToFirstChunk.p50`, `timeToFirstChunk.p90`, `timeToFirstChunk.p95`, `timeToFirstChunk.p99` | Root span time to first chunk percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
812
|
+
| `timeToFirstChunk.count` | Number of traces whose root span recorded a time to first chunk. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
813
|
+
| `timeToFirstToken.avg`, `timeToFirstToken.min`, `timeToFirstToken.max` | Root span time to first token in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
814
|
+
| `timeToFirstToken.p50`, `timeToFirstToken.p90`, `timeToFirstToken.p95`, `timeToFirstToken.p99` | Root span time to first token percentile in milliseconds. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
815
|
+
| `timeToFirstToken.count` | Number of traces whose root span recorded a time to first token. Requires the `aggregateTimeToFirstMeasures` capability. |
|
|
841
816
|
| `errorCount` | Number of traces whose root span recorded an error. |
|
|
842
817
|
| `errorRate` | `errorCount` divided by `count`, from 0 to 1. |
|
|
843
818
|
| `tokens.input.sum`, `tokens.input.avg` | Input tokens. |
|
|
@@ -846,12 +821,6 @@ Every dimension except `executionSource` is also a trace-scope `where` field, so
|
|
|
846
821
|
| `tokens.reasoning.sum`, `tokens.reasoning.avg` | Reasoning output tokens. |
|
|
847
822
|
| `tokens.cached.sum`, `tokens.cached.avg` | Input tokens read from the provider's cache. |
|
|
848
823
|
| `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
824
|
|
|
856
825
|
Numeric measures over metadata aren't supported.
|
|
857
826
|
|
|
@@ -872,16 +841,11 @@ When you request any `cost.*` measure, every row also includes a `cost` object:
|
|
|
872
841
|
|
|
873
842
|
`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
843
|
|
|
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.
|
|
844
|
+
### Time to first chunk (TTFC)
|
|
881
845
|
|
|
882
|
-
|
|
846
|
+
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
847
|
|
|
884
|
-
|
|
848
|
+
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
849
|
|
|
886
850
|
```typescript
|
|
887
851
|
const { capabilities } = await mastraClient.getObservabilityCapabilities()
|
|
@@ -900,6 +864,39 @@ if (capabilities.traceAggregate && capabilities.aggregateTimeToFirstMeasures) {
|
|
|
900
864
|
}
|
|
901
865
|
```
|
|
902
866
|
|
|
867
|
+
### Time to first token (TTFT)
|
|
868
|
+
|
|
869
|
+
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.
|
|
870
|
+
|
|
871
|
+
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.
|
|
872
|
+
|
|
873
|
+
### First chunk and token span types
|
|
874
|
+
|
|
875
|
+
These span types record TTFC and TTFT:
|
|
876
|
+
|
|
877
|
+
- `model_inference`: each provider call.
|
|
878
|
+
- `model_step`: each step of a generation, with the values of the inference that streamed the step's first chunk.
|
|
879
|
+
- `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.
|
|
880
|
+
- `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.
|
|
881
|
+
|
|
882
|
+
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.
|
|
883
|
+
|
|
884
|
+
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.
|
|
885
|
+
|
|
886
|
+
Mastra storage keeps TTFT in its own column, not in the stored `attributes`. Read it from the span's `timeToFirstTokenMs` field.
|
|
887
|
+
|
|
888
|
+
### Missing first chunk and token values
|
|
889
|
+
|
|
890
|
+
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.
|
|
891
|
+
|
|
892
|
+
- In predicates, `null` counts as missing. It matches `notExists` and never matches ordered predicates.
|
|
893
|
+
- In `orderBy`, missing values sort last in both directions, and `0` sorts as a value.
|
|
894
|
+
- In aggregates, spans and traces without a value are skipped, never counted as 0.
|
|
895
|
+
|
|
896
|
+
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.
|
|
897
|
+
|
|
898
|
+
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.
|
|
899
|
+
|
|
903
900
|
### Filter and order groups
|
|
904
901
|
|
|
905
902
|
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 +1028,7 @@ Aggregation uses the same span predicates as [`querySpans()`](#query-spans), wit
|
|
|
1031
1028
|
|
|
1032
1029
|
`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
1030
|
|
|
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.
|
|
1031
|
+
`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
1032
|
|
|
1043
1033
|
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
1034
|
|