@mastra/client-js 1.57.0-alpha.5 → 1.57.0-alpha.7

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.
@@ -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.5"
6
+ version: "1.57.0-alpha.7"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.57.0-alpha.5",
2
+ "version": "1.57.0-alpha.7",
3
3
  "package": "@mastra/client-js",
4
4
  "exports": {},
5
5
  "modules": {}
@@ -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 uses `AgentChunkType`, with `ThreadHistoryChunk` for stored history. 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. Internal runtime events aren't part of these public APIs.
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 runs aren't. [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.
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 runs or reconstruct fragments that weren't retained.
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
  });