@mastra/client-js 1.51.0-alpha.8 → 1.51.0-alpha.9
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/docs/SKILL.md +1 -1
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-harness-agent-controller.md +5 -3
- package/dist/docs/references/docs-harness-schedules.md +1 -1
- package/dist/docs/references/docs-harness-signals.md +2 -2
- package/dist/docs/references/reference-client-js-agent-controller.md +1 -1
- package/dist/docs/references/reference-observability-tracing-trace-query.md +37 -16
- package/dist/route-types.generated.d.ts +2 -0
- package/dist/route-types.generated.d.ts.map +1 -1
- package/package.json +4 -4
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-client-js
|
|
|
3
3
|
description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/client-js"
|
|
6
|
-
version: "1.51.0-alpha.
|
|
6
|
+
version: "1.51.0-alpha.9"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -401,7 +401,7 @@ Create the session under `thread.resourceId`. Because a session can bind only th
|
|
|
401
401
|
|
|
402
402
|
Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
|
|
403
403
|
|
|
404
|
-
`resolveSession` also runs when a user answers an approval card, with that action's request context
|
|
404
|
+
`resolveSession` also runs when a user answers an approval card, with that action's request context. A shared install revalidates the person approving rather than trusting the person who sent the original message.
|
|
405
405
|
|
|
406
406
|
### Handle stale approvals
|
|
407
407
|
|
|
@@ -470,7 +470,7 @@ const subscription = await session.subscribe({
|
|
|
470
470
|
subscription.unsubscribe()
|
|
471
471
|
```
|
|
472
472
|
|
|
473
|
-
`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect
|
|
473
|
+
`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff.
|
|
474
474
|
|
|
475
475
|
The server doesn't replay events missed while the stream was down, so read `session.state()` from `onReconnect` for the current mode, model, and thread. The client surface has no `session.displayState.get()`.
|
|
476
476
|
|
|
@@ -483,4 +483,6 @@ Send work with `session.sendMessage(content)`, or `session.sendMessage({ content
|
|
|
483
483
|
- [Agents](https://mastra.ai/docs/agents/overview)
|
|
484
484
|
- [Workspace](https://mastra.ai/docs/sandbox/overview)
|
|
485
485
|
- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
|
|
486
|
-
- [Channels](https://mastra.ai/docs/channels)
|
|
486
|
+
- [Channels](https://mastra.ai/docs/channels)
|
|
487
|
+
- [Mastra Code](https://code.mastra.ai)
|
|
488
|
+
- [Mastra Factory](https://factory.mastra.ai)
|
|
@@ -73,7 +73,7 @@ Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing i
|
|
|
73
73
|
|
|
74
74
|
### Threaded
|
|
75
75
|
|
|
76
|
-
With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/harness/signals) into that thread
|
|
76
|
+
With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/harness/signals) into that thread. The prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
|
|
77
77
|
|
|
78
78
|
```typescript
|
|
79
79
|
await mastra.schedules.create({
|
|
@@ -218,7 +218,7 @@ export const agentsMdReminderProcessor: Processor = {
|
|
|
218
218
|
}
|
|
219
219
|
```
|
|
220
220
|
|
|
221
|
-
Reactive signals default to `tagName: 'system-reminder'
|
|
221
|
+
Reactive signals default to `tagName: 'system-reminder'`. The model receives this context as
|
|
222
222
|
|
|
223
223
|
```xml
|
|
224
224
|
<system-reminder type="dynamic-agents-md" path="packages/ui/AGENTS.md">
|
|
@@ -411,7 +411,7 @@ export const mastra = new Mastra({
|
|
|
411
411
|
})
|
|
412
412
|
```
|
|
413
413
|
|
|
414
|
-
`RedisStreamsPubSub` implements both the event delivery contract and distributed leasing
|
|
414
|
+
`RedisStreamsPubSub` implements both the event delivery contract and distributed leasing. A single backend handles cross-instance signal delivery and lease ownership. Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
|
|
415
415
|
|
|
416
416
|
## Compatibility and APIs
|
|
417
417
|
|
|
@@ -91,7 +91,7 @@ Returns: `Promise<CreateAgentControllerSessionResponse>`
|
|
|
91
91
|
|
|
92
92
|
### `subscribe(options)`
|
|
93
93
|
|
|
94
|
-
Subscribes to the session's event stream over SSE. The promise resolves once the stream is established and rejects when it can't connect
|
|
94
|
+
Subscribes to the session's event stream over SSE. The promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect` only governs re-establishing a stream that drops after it was established. To retry the initial connection, loop around `subscribe()`.
|
|
95
95
|
|
|
96
96
|
**onEvent** (`(event: AgentControllerEvent) => void`): Called for each event received over the stream. See Events for the event types.
|
|
97
97
|
|
|
@@ -283,21 +283,21 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
|
|
|
283
283
|
|
|
284
284
|
## Fields and operators
|
|
285
285
|
|
|
286
|
-
| Predicate context | Fields
|
|
287
|
-
| ----------------- |
|
|
288
|
-
| Trace | `traceId`, `threadId`, `resourceId`, `entityName`, `entityType`, `environment`, `status` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
289
|
-
| Trace metadata | `metadata.<key>`
|
|
290
|
-
| Trace | `startedAt`, `endedAt`, `durationMs`
|
|
291
|
-
| Trace | `tags`
|
|
292
|
-
| Span | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
293
|
-
| Span | `startedAt`, `endedAt`, `durationMs`
|
|
294
|
-
| Span | `error`
|
|
295
|
-
| Score | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`
|
|
296
|
-
| Score | `score`, `timestamp`
|
|
297
|
-
| Score | `spanId`
|
|
298
|
-
| Feedback | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`
|
|
299
|
-
| Feedback | `value`, `timestamp`
|
|
300
|
-
| Feedback | `comment`
|
|
286
|
+
| Predicate context | Fields | Operators |
|
|
287
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
288
|
+
| Trace | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityName`, `entityType`, `environment`, `status` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
289
|
+
| Trace metadata | `metadata.<key>` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
290
|
+
| Trace | `startedAt`, `endedAt`, `durationMs` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
291
|
+
| Trace | `tags` | `includes`, `notIncludes`, `exists`, `notExists` |
|
|
292
|
+
| Span | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`, `runId`, `sessionId`, `userId`, `organizationId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
293
|
+
| Span | `startedAt`, `endedAt`, `durationMs` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
294
|
+
| Span | `error` | `exists`, `notExists` |
|
|
295
|
+
| Score | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
296
|
+
| Score | `score`, `timestamp` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
297
|
+
| Score | `spanId` | `exists`, `notExists` |
|
|
298
|
+
| Feedback | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
299
|
+
| Feedback | `value`, `timestamp` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
300
|
+
| Feedback | `comment` | `exists`, `notExists` |
|
|
301
301
|
|
|
302
302
|
Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`. Tag predicates name the stored tag collection in `path`. `includes` and `notIncludes` also take one tag in `value`, while `exists` and `notExists` take only `op` and `path`. See [Filter by tags](#filter-by-tags).
|
|
303
303
|
|
|
@@ -319,6 +319,27 @@ This top-level predicate doesn't inspect child spans. In contrast, `spans.some`
|
|
|
319
319
|
|
|
320
320
|
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`.
|
|
321
321
|
|
|
322
|
+
### Filter by context identifiers
|
|
323
|
+
|
|
324
|
+
`runId`, `sessionId`, `userId`, and `organizationId` are available at trace scope and inside `spans.some` / `spans.none`. Trace-scope predicates read the current root span. Span-scope predicates bind to one related current span, so a run recorded only on a child span is found through `spans.some`:
|
|
325
|
+
|
|
326
|
+
```typescript
|
|
327
|
+
const sessionTracesWithRun = {
|
|
328
|
+
op: 'and',
|
|
329
|
+
args: [
|
|
330
|
+
{ op: 'eq', left: { path: 'organizationId' }, right: { literal: 'org-123' } },
|
|
331
|
+
{ op: 'eq', left: { path: 'sessionId' }, right: { literal: 'session-123' } },
|
|
332
|
+
{
|
|
333
|
+
spans: {
|
|
334
|
+
some: { op: 'eq', left: { path: 'runId' }, right: { literal: 'run-42' } },
|
|
335
|
+
},
|
|
336
|
+
},
|
|
337
|
+
],
|
|
338
|
+
}
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
These identifiers support `eq`, `ne`, `in`, `notIn`, `exists`, and `notExists`. Field discovery lists them, but value discovery doesn't return their recorded values. Stores advertise support through the `trace-query-context-ids` feature. A predicate on one of these fields against an older store returns `501` before storage runs, and field discovery omits them for that store.
|
|
342
|
+
|
|
322
343
|
### Filter by span properties
|
|
323
344
|
|
|
324
345
|
Every condition inside one `spans.some` or `spans.none` clause applies to the same current span. For example, this predicate finds a failed tool span whose name is `medication_lookup`; a matching name on one span and an error on another don't satisfy it:
|
|
@@ -679,7 +700,7 @@ const plan = planTraceQuery(parseTraceQueryRequest(request), {
|
|
|
679
700
|
})
|
|
680
701
|
```
|
|
681
702
|
|
|
682
|
-
`resourceId` is optional and narrows within the organization. Keyset and delta cursors are bound to the scope
|
|
703
|
+
`resourceId` is optional and narrows within the organization. Keyset and delta cursors are bound to the scope. A cursor created under one scope and reused under another returns `409` before storage runs. A scoped request against an observability store or `@mastra/core` that predates tenant scope returns `501` instead of running unscoped. Stores advertise support through the `trace-query-tenant-scope` feature. Callers can't name `projectId` in predicates. An `organizationId` predicate compares recorded data and is ANDed with the scope, so it can only narrow the tenant's own traces and never widens it. Without a scope the routes behave as before, so self-hosted installations keep their own tenant model.
|
|
683
704
|
|
|
684
705
|
Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
|
|
685
706
|
|
|
@@ -2671,6 +2671,8 @@ type Shared_Type_65 = {
|
|
|
2671
2671
|
traceQuery: boolean;
|
|
2672
2672
|
/** `durationMs` predicates in trace and thread queries */
|
|
2673
2673
|
traceQueryRootDuration: boolean;
|
|
2674
|
+
/** `runId`, `sessionId`, `userId` and `organizationId` predicates in trace and thread queries */
|
|
2675
|
+
traceQueryContextIds: boolean;
|
|
2674
2676
|
/** Trace query field discovery (POST /observability/traces/query/fields and /values) */
|
|
2675
2677
|
traceQueryDiscovery: boolean;
|
|
2676
2678
|
/** Trusted tenant scoping of trace and thread queries */
|