@mastra/client-js 1.57.0-alpha.5 → 1.57.0-alpha.6
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-signals-thread-streams.md +34 -3
- package/dist/docs/references/reference-client-js-agents.md +2 -0
- package/dist/index.cjs +3 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/resources/agent.d.ts +4 -2
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/route-types.generated.d.ts +2 -0
- package/dist/route-types.generated.d.ts.map +1 -1
- package/dist/types.d.ts +6 -4
- package/dist/types.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.57.0-alpha.
|
|
6
|
+
version: "1.57.0-alpha.6"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -51,13 +51,42 @@ Pass `withInitialHistory: true` to begin with a `thread-history` chunk, which ca
|
|
|
51
51
|
|
|
52
52
|
Use `runId` to group chunks from the same run. The exception is [`thread-history`](https://mastra.ai/reference/streaming/ChunkType), which has an empty `runId` because its messages can span several runs. The subscription's [`activeRunId()`](https://mastra.ai/reference/agents/agent) returns the active run's ID or `null`.
|
|
53
53
|
|
|
54
|
-
The public stream
|
|
54
|
+
The public subscription stream includes `AgentChunkType`. `withInitialHistory` adds `ThreadHistoryChunk`, and `withRunStatus: true` adds `ThreadRunStatusChunk`. Both options default to `false`. The [ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) lists the fields for model output, tool calls and results, approvals, aborts, and errors. To observe queue counts, use [`subscribeThreadEvents()`](https://mastra.ai/reference/signals/thread-events) separately.
|
|
55
|
+
|
|
56
|
+
### Detect when a run finishes
|
|
57
|
+
|
|
58
|
+
Pass `withRunStatus: true` to opt in to run outcomes. Existing subscriptions don't receive these chunks by default.
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
const subscription = await agent.subscribeToThread({
|
|
62
|
+
resourceId: 'user-123',
|
|
63
|
+
threadId: 'thread-456',
|
|
64
|
+
withRunStatus: true,
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
A [`thread-run-status`](https://mastra.ai/reference/streaming/ChunkType) chunk identifies the run's outcome independently of its output:
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
const chunk = {
|
|
72
|
+
type: 'thread-run-status',
|
|
73
|
+
runId: 'run-123',
|
|
74
|
+
from: 'AGENT',
|
|
75
|
+
payload: { status: 'success' },
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`status` is `success`, `failed`, `aborted`, or `suspended`. Live output arrives before its status. A suspension is resumable: the same run can later produce more output and a final status. A run outcome doesn't close the thread subscription, which continues listening for later runs.
|
|
80
|
+
|
|
81
|
+
With `withInitialHistory`, the first chunk's payload is `{ messages, hasMore, activeRunId }`. `activeRunId` identifies the run holding thread ownership during hydration, or is `null` when idle. Use `thread-run-status` to determine the outcome. An idle thread alone doesn't indicate success.
|
|
82
|
+
|
|
83
|
+
With `withRunStatus: true`, retained outcomes are delivered even when a run finished before you subscribed and its text is already in history. A late subscriber using both options receives one status for every still-retained finished run, including runs outside the initial history page. It doesn't receive only the newest run's status. Final outcomes are deduplicated within one subscription. Suspension notifications are deduplicated per execution segment. A reconnect creates a new subscription and may deliver the same outcome again. Group updates by `runId` rather than treating each delivery as a new answer.
|
|
55
84
|
|
|
56
85
|
### Approve tool calls
|
|
57
86
|
|
|
58
87
|
When a run pauses for tool approval, send your decision with [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents) or the [server approval route](https://mastra.ai/reference/server/routes). The existing subscription receives output when the run resumes.
|
|
59
88
|
|
|
60
|
-
A paused run keeps ownership of the thread. Signals that try to start a new run receive an `accepted` action of `blocked` until the paused run resumes or is aborted. Pending approvals and suspensions are replayed when you subscribe again. Completed
|
|
89
|
+
A paused run keeps ownership of the thread. Signals that try to start a new run receive an `accepted` action of `blocked` until the paused run resumes or is aborted. Pending approvals and suspensions are replayed when you subscribe again. Completed stored output isn't replayed. Retained run outcomes are delivered when `withRunStatus: true`. [When the agent sees your input](https://mastra.ai/docs/signals/sending-signals) covers the interrupt and wait rules for input that arrives during a run.
|
|
61
90
|
|
|
62
91
|
### Filter signals in a subscription
|
|
63
92
|
|
|
@@ -73,7 +102,9 @@ Use `reconnect: true` for long-lived subscriptions. `processDataStream()` then r
|
|
|
73
102
|
|
|
74
103
|
A reconnect can resume output that the shared [PubSub backend](https://mastra.ai/docs/server/pubsub) still retains. It can't recover events held only in another process's in-memory cache. Use `withInitialHistory` to reload the newest page of stored messages when you need conversation history.
|
|
75
104
|
|
|
76
|
-
Stored messages aren't a recording of every streamed text fragment. Reconnecting doesn't replay completed stored
|
|
105
|
+
Stored messages aren't a recording of every streamed text fragment. Reconnecting doesn't replay completed stored output or reconstruct fragments that weren't retained.
|
|
106
|
+
|
|
107
|
+
Outcome recovery is bounded by the PubSub backend's retention, not by the history page size. Redis Streams keeps compact terminal events and execution authority metadata when saved output is trimmed, but its configured stream length and idle TTL can still evict them. This isn't a permanent run audit log or a guaranteed time window. Upgrade both `@mastra/core` and `@mastra/redis-streams` for recovery after trimming. Older adapters may delete terminal events with the output.
|
|
77
108
|
|
|
78
109
|
### SSE heartbeats for custom endpoints
|
|
79
110
|
|
|
@@ -349,6 +349,8 @@ const { messages, initialHistoryPagination } = useChat({
|
|
|
349
349
|
|
|
350
350
|
**threadId** (`string`): Thread ID to subscribe to.
|
|
351
351
|
|
|
352
|
+
**withRunStatus** (`boolean`): Emit live and retained thread-run-status outcomes. Callback types include these chunks only when requested. useChat enables this for its thread subscription. (Default: `false`)
|
|
353
|
+
|
|
352
354
|
**processDataStream().reconnect** (`boolean | { maxRetries?: number; delayMs?: number }`): Reconnects the subscription stream after it closes or a reconnect request fails. true retries indefinitely with a one-second delay. A 4xx (other than 408 and 429) or 501 response stops reconnecting and rejects with that error.
|
|
353
355
|
|
|
354
356
|
The subscription also exposes `abort(options?)` and `unsubscribe()`. `await subscription.abort({ clearPendingSignals: true })` requests an abort and clears pending signals without closing the subscription. Omit the flag to preserve pending input. `unsubscribe()` closes the subscription without aborting the run.
|
package/dist/index.cjs
CHANGED
|
@@ -1664,13 +1664,14 @@ var Agent = class extends BaseResource {
|
|
|
1664
1664
|
return this.requestSignalRoute(`/agents/${this.agentId}/queue-signal`, params);
|
|
1665
1665
|
}
|
|
1666
1666
|
async subscribeToThread(params) {
|
|
1667
|
-
const { resourceId, threadId, withInitialHistory } = params;
|
|
1667
|
+
const { resourceId, threadId, withInitialHistory, withRunStatus } = params;
|
|
1668
1668
|
const requestSubscription = () => this.request(`/agents/${this.agentId}/threads/subscribe`, {
|
|
1669
1669
|
method: "POST",
|
|
1670
1670
|
body: {
|
|
1671
1671
|
resourceId,
|
|
1672
1672
|
threadId,
|
|
1673
|
-
...withInitialHistory ? { withInitialHistory } : {}
|
|
1673
|
+
...withInitialHistory ? { withInitialHistory } : {},
|
|
1674
|
+
...withRunStatus ? { withRunStatus } : {}
|
|
1674
1675
|
},
|
|
1675
1676
|
stream: true
|
|
1676
1677
|
});
|