@mastra/client-js 0.0.0-studio-deploy-20260404184540 → 0.0.0-studio-cli-20260504022012

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.
Files changed (39) hide show
  1. package/CHANGELOG.md +903 -3
  2. package/dist/_types/@internal_ai-sdk-v5/dist/index.d.ts +466 -1764
  3. package/dist/client.d.ts +46 -3
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/docs/SKILL.md +3 -1
  6. package/dist/docs/assets/SOURCE_MAP.json +7 -2
  7. package/dist/docs/references/docs-editor-overview.md +290 -0
  8. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +95 -0
  9. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +15 -0
  10. package/dist/docs/references/reference-client-js-agents.md +166 -0
  11. package/dist/docs/references/reference-client-js-mastra-client.md +23 -0
  12. package/dist/docs/references/reference-client-js-observability.md +2 -2
  13. package/dist/docs/references/reference-client-js-workflows.md +62 -1
  14. package/dist/index.cjs +660 -35
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.ts +2 -0
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +657 -35
  19. package/dist/index.js.map +1 -1
  20. package/dist/resources/a2a.d.ts +56 -10
  21. package/dist/resources/a2a.d.ts.map +1 -1
  22. package/dist/resources/agent.d.ts +69 -0
  23. package/dist/resources/agent.d.ts.map +1 -1
  24. package/dist/resources/channels.d.ts +63 -0
  25. package/dist/resources/channels.d.ts.map +1 -0
  26. package/dist/resources/index.d.ts +1 -0
  27. package/dist/resources/index.d.ts.map +1 -1
  28. package/dist/resources/memory-thread.d.ts.map +1 -1
  29. package/dist/resources/observability.d.ts +18 -1
  30. package/dist/resources/observability.d.ts.map +1 -1
  31. package/dist/resources/run.d.ts +26 -2
  32. package/dist/resources/run.d.ts.map +1 -1
  33. package/dist/resources/vector.d.ts +5 -5
  34. package/dist/resources/vector.d.ts.map +1 -1
  35. package/dist/types.d.ts +115 -6
  36. package/dist/types.d.ts.map +1 -1
  37. package/dist/utils/process-a2a-stream.d.ts +4 -0
  38. package/dist/utils/process-a2a-stream.d.ts.map +1 -0
  39. package/package.json +12 -12
@@ -151,6 +151,30 @@ for await (const part of uiMessageStream) {
151
151
  }
152
152
  ```
153
153
 
154
+ ### `streamUntilIdle()`
155
+
156
+ Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
157
+
158
+ ```typescript
159
+ const response = await agent.streamUntilIdle('Research solana for me', {
160
+ memory: {
161
+ thread: 'thread-1',
162
+ resource: 'resource-1',
163
+ },
164
+ maxIdleMs: 5 * 60_000,
165
+ })
166
+
167
+ response.processDataStream({
168
+ onChunk: async chunk => {
169
+ if (chunk.type === 'background-task-completed') {
170
+ console.log('task complete:', chunk.payload.taskId)
171
+ }
172
+ },
173
+ })
174
+ ```
175
+
176
+ The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
177
+
154
178
  ### `getTool()`
155
179
 
156
180
  Retrieve information about a specific tool available to the agent:
@@ -217,6 +241,26 @@ response.processDataStream({
217
241
  })
218
242
  ```
219
243
 
244
+ ### `resumeStream()`
245
+
246
+ Resume a suspended agent stream with custom data. Use this to continue execution after a suspension point, such as a workflow suspend within an agent:
247
+
248
+ ```typescript
249
+ const response = await agent.resumeStream(
250
+ { approved: true, selectedOption: 'plan-b' },
251
+ {
252
+ runId: 'run-123',
253
+ toolCallId: 'tool-call-456', // optional
254
+ },
255
+ )
256
+
257
+ await response.processDataStream({
258
+ onChunk: chunk => {
259
+ console.log(chunk)
260
+ },
261
+ })
262
+ ```
263
+
220
264
  ### `approveToolCallGenerate()`
221
265
 
222
266
  Approve a pending tool call when using `generate()` (non-streaming). Returns the complete response:
@@ -439,4 +483,126 @@ Delete a stored agent:
439
483
  ```typescript
440
484
  const result = await storedAgent.delete()
441
485
  console.log(result.success) // true
486
+ ```
487
+
488
+ ## Version management
489
+
490
+ Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See the [Editor overview](https://mastra.ai/docs/editor/overview) for an introduction to version management.
491
+
492
+ ### Getting an agent with a specific version
493
+
494
+ Pass a version identifier when getting an agent:
495
+
496
+ ```typescript
497
+ // Load the published version (default)
498
+ const agent = mastraClient.getAgent('support-agent')
499
+
500
+ // Load the latest draft
501
+ const draftAgent = mastraClient.getAgent('support-agent', { status: 'draft' })
502
+
503
+ // Load a specific version
504
+ const versionedAgent = mastraClient.getAgent('support-agent', { versionId: 'abc-123' })
505
+ ```
506
+
507
+ For stored agents, pass a status option to `details()`:
508
+
509
+ ```typescript
510
+ const storedAgent = mastraClient.getStoredAgent('my-agent')
511
+ const draft = await storedAgent.details(undefined, { status: 'draft' })
512
+ ```
513
+
514
+ ### `listVersions()`
515
+
516
+ List all versions for an agent:
517
+
518
+ ```typescript
519
+ const versions = await agent.listVersions()
520
+ console.log(versions.items) // Array of version snapshots
521
+ console.log(versions.total)
522
+ ```
523
+
524
+ With pagination and sorting:
525
+
526
+ ```typescript
527
+ const versions = await agent.listVersions({
528
+ page: 0,
529
+ perPage: 10,
530
+ orderBy: {
531
+ field: 'createdAt',
532
+ direction: 'DESC',
533
+ },
534
+ })
535
+ ```
536
+
537
+ ### `createVersion()`
538
+
539
+ Create a new version snapshot:
540
+
541
+ ```typescript
542
+ const version = await agent.createVersion({
543
+ changeMessage: 'Updated tone to be more friendly',
544
+ })
545
+ ```
546
+
547
+ ### `getVersion()`
548
+
549
+ Get a specific version by ID:
550
+
551
+ ```typescript
552
+ const version = await agent.getVersion('version-123')
553
+ console.log(version.versionNumber)
554
+ console.log(version.changedFields)
555
+ console.log(version.createdAt)
556
+ ```
557
+
558
+ ### `activateVersion()`
559
+
560
+ Set a version as the active published version:
561
+
562
+ ```typescript
563
+ await agent.activateVersion('version-123')
564
+ ```
565
+
566
+ ### `restoreVersion()`
567
+
568
+ Restore a previous version by creating a new version with the same configuration:
569
+
570
+ ```typescript
571
+ await agent.restoreVersion('version-456')
572
+ ```
573
+
574
+ ### `deleteVersion()`
575
+
576
+ Delete a version:
577
+
578
+ ```typescript
579
+ await agent.deleteVersion('version-789')
580
+ ```
581
+
582
+ ### `compareVersions()`
583
+
584
+ Compare two versions and return their differences:
585
+
586
+ ```typescript
587
+ const diff = await agent.compareVersions('version-123', 'version-456')
588
+ console.log(diff.changes) // Fields that changed between versions
589
+ ```
590
+
591
+ ### React SDK
592
+
593
+ In the React SDK, pass an `agentVersionId` through `requestContext` when using the `useChat` hook:
594
+
595
+ ```typescript
596
+ import { useChat } from '@mastra/react'
597
+
598
+ function Chat() {
599
+ const { messages, input, handleInputChange, handleSubmit } = useChat({
600
+ agentId: 'support-agent',
601
+ requestContext: {
602
+ agentVersionId: 'abc-123',
603
+ },
604
+ })
605
+
606
+ // ... render chat UI
607
+ }
442
608
  ```
@@ -12,6 +12,29 @@ export const mastraClient = new MastraClient({
12
12
  })
13
13
  ```
14
14
 
15
+ ## `RequestContext`
16
+
17
+ When you use `RequestContext` with the client SDK, import it from `@mastra/client-js`.
18
+
19
+ ```typescript
20
+ import { MastraClient, RequestContext } from '@mastra/client-js'
21
+
22
+ const client = new MastraClient({
23
+ baseUrl: 'http://localhost:4111/',
24
+ })
25
+
26
+ const requestContext = new RequestContext()
27
+ requestContext.set('userId', 'user-123')
28
+
29
+ const agent = client.getAgent('support-agent')
30
+
31
+ const response = await agent.generate('Summarize this ticket', {
32
+ requestContext,
33
+ })
34
+ ```
35
+
36
+ You can also pass `requestContext` as a `Record<string, any>`.
37
+
15
38
  ## Parameters
16
39
 
17
40
  **baseUrl** (`string`): The base URL for the Mastra API. All requests will be sent relative to this URL.
@@ -68,5 +68,5 @@ const scores = await mastraClient.listScoresBySpan({
68
68
 
69
69
  ## Related
70
70
 
71
- - [Agents API](https://mastra.ai/reference/client-js/agents) - Learn about agent interactions that generate traces
72
- - [Workflows API](https://mastra.ai/reference/client-js/workflows) - Understand workflow execution monitoring
71
+ - [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces
72
+ - [Workflows API](https://mastra.ai/reference/client-js/workflows): Understand workflow execution monitoring
@@ -140,6 +140,18 @@ await run.resume({
140
140
  })
141
141
  ```
142
142
 
143
+ When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
144
+
145
+ ```typescript
146
+ await run.resume({
147
+ step: 'approve',
148
+ resumeData: { ok: true },
149
+ forEachIndex: 1, // resumes the second iteration
150
+ })
151
+ ```
152
+
153
+ `forEachIndex` is also supported by `resumeAsync()` and `resumeStream()`.
154
+
143
155
  ### `cancel()`
144
156
 
145
157
  Cancel a running workflow:
@@ -196,4 +208,53 @@ A workflow run result yields the following:
196
208
 
197
209
  **eventTimestamp** (`Date`): The timestamp of the event
198
210
 
199
- **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
211
+ **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
212
+
213
+ ## Schedules
214
+
215
+ Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing them at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
216
+
217
+ ### `listSchedules()`
218
+
219
+ List all schedules, optionally filtered by workflow id or status.
220
+
221
+ ```typescript
222
+ const schedules = await mastraClient.listSchedules({
223
+ workflowId: 'daily-report',
224
+ status: 'active',
225
+ })
226
+ ```
227
+
228
+ ### `getSchedule()`
229
+
230
+ Fetch a single schedule by id.
231
+
232
+ ```typescript
233
+ const schedule = await mastraClient.getSchedule('daily-report')
234
+ ```
235
+
236
+ ### `pauseSchedule()`
237
+
238
+ Pause a schedule so the scheduler stops firing it. Returns the updated schedule. Idempotent.
239
+
240
+ ```typescript
241
+ await mastraClient.pauseSchedule('daily-report')
242
+ ```
243
+
244
+ ### `resumeSchedule()`
245
+
246
+ Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule does not fire a backlog. Returns the updated schedule. Idempotent.
247
+
248
+ ```typescript
249
+ await mastraClient.resumeSchedule('daily-report')
250
+ ```
251
+
252
+ ### `listScheduleTriggers()`
253
+
254
+ List the trigger history for a schedule, including the joined run summary for each fire.
255
+
256
+ ```typescript
257
+ const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {
258
+ limit: 50,
259
+ })
260
+ ```