@mastra/client-js 1.21.1 → 1.21.2-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mastra/client-js
 
+## 1.21.2-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`d779de3`](https://github.com/mastra-ai/mastra/commit/d779de3cd9d2e7ed8110547190e2f15e786a0e41), [`1750c97`](https://github.com/mastra-ai/mastra/commit/1750c975d6179fbf6db2813b15229d4f8f23fc55), [`0e32507`](https://github.com/mastra-ai/mastra/commit/0e32507962cdfa5569b7bda5bc6fb3dd34e40b03), [`3a081c1`](https://github.com/mastra-ai/mastra/commit/3a081c1255c5ae8c99f6dad91cc612934ef6f2bd), [`fe9eacd`](https://github.com/mastra-ai/mastra/commit/fe9eacd9545a0a9d64aad31c9fa90294a425289e), [`db79c86`](https://github.com/mastra-ai/mastra/commit/db79c86c60723d57e02f9636ca2611bd4515f194)]:
+  - @mastra/core@1.38.0-alpha.2
+
+## 1.21.2-alpha.1
+
+### Patch Changes
+
+- Fixed sub-agent version resolution in supervisor mode. Sub-agents now inherit the parent's draft/published version semantics — when chatting in the editor (draft mode), sub-agents resolve to their latest draft version; in the main agent chat (published mode), sub-agents resolve to their published version. Previously, sub-agents without explicit per-agent version overrides always fell back to the code-defined default, ignoring the parent's version context. ([#17165](https://github.com/mastra-ai/mastra/pull/17165))
+
+- Updated dependencies [[`49f8abc`](https://github.com/mastra-ai/mastra/commit/49f8abce8258e4f2f87bd326acfbdb641264a47c)]:
+  - @mastra/core@1.37.2-alpha.1
+
+## 1.21.2-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`07c3de7`](https://github.com/mastra-ai/mastra/commit/07c3de7f7bc418beccaea3b5e6b7f7cdda79d492)]:
+  - @mastra/core@1.37.2-alpha.0
+
 ## 1.21.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.21.1"
+  version: "1.21.2-alpha.2"
 ---
 
 ## When to use
@@ -33,6 +33,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: toAISdkStream()](references/reference-ai-sdk-to-ai-sdk-stream.md) - API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
 - [Reference: toAISdkV4Messages()](references/reference-ai-sdk-to-ai-sdk-v4-messages.md) - API reference for toAISdkV4Messages(), a function to convert Mastra messages to AI SDK v4 UI messages.
 - [Reference: toAISdkV5Messages()](references/reference-ai-sdk-to-ai-sdk-v5-messages.md) - API reference for toAISdkV5Messages(), a function to convert Mastra messages to AI SDK v5 UI messages.
+- [Reference: Agent Builder API](references/reference-client-js-agent-builder.md) - Learn how to interact with Agent Builder actions, including starting runs, streaming progress, resuming suspended steps, and observing runs using the client-js SDK.
 - [Reference: Agents API](references/reference-client-js-agents.md) - Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
 - [Reference: OpenAI Responses API Conversations](references/reference-client-js-conversations.md) - API reference for the client-js helpers that call Mastra's OpenAI-compatible `/v1/conversations` routes.
 - [Reference: Error handling](references/reference-client-js-error-handling.md) - Learn about the built-in retry mechanism and error handling capabilities in the Mastra client-js SDK.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.1",
+  "version": "1.21.2-alpha.2",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/docs/references/reference-client-js-agent-builder.md

@@ -0,0 +1,161 @@
+# Agent Builder API
+
+The Agent Builder API provides methods to interact with [Agent Builder](https://mastra.ai/docs/agent-builder/overview) actions on the server. Each action is a workflow exposed under `/agent-builder/:actionId/*`. The Builder must be enabled on the server via `MastraEditor.builder.enabled`, with a valid `MASTRA_EE_LICENSE` in production.
+
+## Getting all actions
+
+Retrieve a record of available Agent Builder actions:
+
+```typescript
+const actions = await mastraClient.getAgentBuilderActions()
+```
+
+Returns a `Record<string, WorkflowInfo>` keyed by action ID.
+
+## Working with a specific action
+
+Get an instance of a specific action by its ID:
+
+```typescript
+const action = mastraClient.getAgentBuilderAction('create-agent')
+```
+
+## Action methods
+
+### `details()`
+
+Retrieve metadata about an Agent Builder action:
+
+```typescript
+const info = await action.details()
+```
+
+### `createRun()`
+
+Create a new run for this action and receive a `runId`. Use the returned id with `startActionRun()`, `stream()`, `resume()`, or `observeStream()`.
+
+```typescript
+const { runId } = await action.createRun()
+```
+
+You can also pass an explicit `runId`:
+
+```typescript
+const { runId } = await action.createRun({ runId: 'my-run-id' })
+```
+
+### `startAsync()`
+
+Start the action and wait for completion. Returns the final `AgentBuilderActionResult` with `success`, `applied`, `branchName`, `message`, `validationResults`, `error`, `errors`, and `stepResults`.
+
+```typescript
+const result = await action.startAsync({
+  inputData: { agentName: 'support-bot' },
+})
+```
+
+Pass an existing `runId` as the second argument to start a previously created run:
+
+```typescript
+const { runId } = await action.createRun()
+const result = await action.startAsync({ inputData }, runId)
+```
+
+### `startActionRun()`
+
+Start an existing run without waiting for completion. Returns `{ message }`.
+
+```typescript
+const { runId } = await action.createRun()
+await action.startActionRun({ inputData }, runId)
+```
+
+### `stream()`
+
+Start an existing run and stream progress events as a `ReadableStream<{ type, payload }>`.
+
+```typescript
+const { runId } = await action.createRun()
+const stream = await action.stream({ inputData }, runId)
+
+for await (const event of stream) {
+  console.log(event.type, event.payload)
+}
+```
+
+### `resume()`
+
+Resume a suspended step on a run. Returns `{ message }`.
+
+```typescript
+await action.resume({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeAsync()`
+
+Resume a suspended step and wait for completion. Returns an `AgentBuilderActionResult`.
+
+```typescript
+const result = await action.resumeAsync({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeStream()`
+
+Resume a suspended step and stream subsequent events.
+
+```typescript
+const stream = await action.resumeStream({
+  runId,
+  step: 'review',
+  resumeData: { approved: true },
+})
+```
+
+### `observeStream()`
+
+Attach to an existing run, replaying cached events from the beginning, then continuing with live events. Use this to recover after a page refresh or hot reload.
+
+```typescript
+const stream = await action.observeStream({ runId })
+```
+
+### `observeStreamLegacy()`
+
+Same as `observeStream()` but uses the legacy streaming endpoint. Prefer `observeStream()` for new code.
+
+```typescript
+const stream = await action.observeStreamLegacy({ runId })
+```
+
+### `runs()`
+
+List runs for this action with optional filters.
+
+```typescript
+const runs = await action.runs({ page: 0, perPage: 20 })
+```
+
+Accepts `fromDate`, `toDate`, `page`, `perPage`, `resourceId`, and legacy `limit`/`offset`.
+
+### `runById()`
+
+Fetch a specific run by ID. Use `fields` to limit the returned payload and `withNestedWorkflows` to skip nested workflow data.
+
+```typescript
+const run = await action.runById(runId, {
+  fields: ['result', 'steps'],
+  withNestedWorkflows: false,
+})
+```
+
+### `cancelRun()`
+
+Cancel an in-flight run.
+
+```typescript
+await action.cancelRun(runId)
+```
+
+## Access control
+
+The `/agent-builder/*` routes are gated by the `agent-builder` permission resource. Calling clients need at minimum `agent-builder:read` and `agent-builder:execute`, plus any picker resources the action touches (`stored-agents`, `stored-skills`, `tools`, `workflows`, `memory`). See [Access control](https://mastra.ai/docs/agent-builder/access-control) for the full grant list.

package/dist/docs/references/reference-client-js-mastra-client.md

@@ -73,6 +73,10 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
+**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
+**getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
 **responses** (`Responses`): Provides OpenAI-style Responses API helpers with \`create()\`, \`retrieve()\`, \`stream()\`, and \`delete()\`.
 
 **conversations** (`Conversations`): Provides conversation helpers with \`create()\`, \`retrieve()\`, \`delete()\`, and \`items.list()\`.

package/dist/route-types.generated.d.ts

@@ -2362,7 +2362,7 @@ export interface PostAgentsAgentIdClone_RouteContract {
     responseType: 'json';
 }
 export type GetAgentsAgentIdVoiceSpeakers_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
 export type GetAgentsAgentIdVoiceSpeakers_Response = {
@@ -2388,14 +2388,17 @@ export interface GetAgentsAgentIdVoiceSpeakers_RouteContract {
     response: GetAgentsAgentIdVoiceSpeakers_Response;
     responseType: 'json';
 }
+/** @deprecated */
 export type GetAgentsAgentIdSpeakers_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
+/** @deprecated */
 export type GetAgentsAgentIdSpeakers_Response = {
     voiceId: string;
     [x: string]: unknown;
 }[];
+/** @deprecated */
 export type GetAgentsAgentIdSpeakers_Request = Simplify<(GetAgentsAgentIdSpeakers_PathParams extends never ? {} : {
     params: GetAgentsAgentIdSpeakers_PathParams;
 }) & (never extends never ? {} : {} extends never ? {
@@ -2407,6 +2410,7 @@ export type GetAgentsAgentIdSpeakers_Request = Simplify<(GetAgentsAgentIdSpeaker
 } : {
     body: never;
 })>;
+/** @deprecated */
 export interface GetAgentsAgentIdSpeakers_RouteContract {
     pathParams: GetAgentsAgentIdSpeakers_PathParams;
     queryParams: never;
@@ -2448,6 +2452,7 @@ export type PostAgentsAgentIdGenerate_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -2564,6 +2569,7 @@ export type PostAgentsAgentIdGenerateVnext_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -2680,6 +2686,7 @@ export type PostAgentsAgentIdStream_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -2796,6 +2803,7 @@ export type PostAgentsAgentIdStreamUntilIdle_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -2915,6 +2923,7 @@ export type PostAgentsAgentIdStreamVnext_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -3153,6 +3162,7 @@ export type PostAgentsAgentIdSignals_Body = {
                         status: 'draft' | 'published';
                     };
                 } | undefined;
+                defaultStatus?: ('draft' | 'published') | undefined;
             } | undefined;
             maxSteps?: number | undefined;
             stopWhen?: any | undefined;
@@ -3401,6 +3411,7 @@ export type PostAgentsAgentIdResumeStream_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -3644,6 +3655,7 @@ export type PostAgentsAgentIdResumeStreamUntilIdle_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -3763,6 +3775,7 @@ export type PostAgentsAgentIdNetwork_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -4088,7 +4101,7 @@ export interface GetAgentsAgentIdSkillsSkillName_RouteContract {
     responseType: 'json';
 }
 export type PostAgentsAgentIdVoiceSpeak_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
 export type PostAgentsAgentIdVoiceSpeak_Body = {
@@ -4115,15 +4128,19 @@ export interface PostAgentsAgentIdVoiceSpeak_RouteContract {
     response: PostAgentsAgentIdVoiceSpeak_Response;
     responseType: 'stream';
 }
+/** @deprecated */
 export type PostAgentsAgentIdSpeak_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
+/** @deprecated */
 export type PostAgentsAgentIdSpeak_Body = {
     text: string;
     speakerId?: string | undefined;
 };
+/** @deprecated */
 export type PostAgentsAgentIdSpeak_Response = any;
+/** @deprecated */
 export type PostAgentsAgentIdSpeak_Request = Simplify<(PostAgentsAgentIdSpeak_PathParams extends never ? {} : {
     params: PostAgentsAgentIdSpeak_PathParams;
 }) & (never extends never ? {} : {} extends never ? {
@@ -4135,6 +4152,7 @@ export type PostAgentsAgentIdSpeak_Request = Simplify<(PostAgentsAgentIdSpeak_Pa
 } : {
     body: PostAgentsAgentIdSpeak_Body;
 })>;
+/** @deprecated */
 export interface PostAgentsAgentIdSpeak_RouteContract {
     pathParams: PostAgentsAgentIdSpeak_PathParams;
     queryParams: never;
@@ -4144,7 +4162,7 @@ export interface PostAgentsAgentIdSpeak_RouteContract {
     responseType: 'stream';
 }
 export type PostAgentsAgentIdVoiceListen_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
 export type PostAgentsAgentIdVoiceListen_Body = {
@@ -4175,19 +4193,23 @@ export interface PostAgentsAgentIdVoiceListen_RouteContract {
     response: PostAgentsAgentIdVoiceListen_Response;
     responseType: 'json';
 }
+/** @deprecated */
 export type PostAgentsAgentIdListen_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
+/** @deprecated */
 export type PostAgentsAgentIdListen_Body = {
     audio: any;
     options?: {
         [key: string]: any;
     } | undefined;
 };
+/** @deprecated */
 export type PostAgentsAgentIdListen_Response = {
     text: string;
 };
+/** @deprecated */
 export type PostAgentsAgentIdListen_Request = Simplify<(PostAgentsAgentIdListen_PathParams extends never ? {} : {
     params: PostAgentsAgentIdListen_PathParams;
 }) & (never extends never ? {} : {} extends never ? {
@@ -4199,6 +4221,7 @@ export type PostAgentsAgentIdListen_Request = Simplify<(PostAgentsAgentIdListen_
 } : {
     body: PostAgentsAgentIdListen_Body;
 })>;
+/** @deprecated */
 export interface PostAgentsAgentIdListen_RouteContract {
     pathParams: PostAgentsAgentIdListen_PathParams;
     queryParams: never;
@@ -4208,7 +4231,7 @@ export interface PostAgentsAgentIdListen_RouteContract {
     responseType: 'json';
 }
 export type GetAgentsAgentIdVoiceListener_PathParams = {
-    /** Unique identifier for the agent */
+    /** Agent ID */
     agentId: string;
 };
 export type GetAgentsAgentIdVoiceListener_Response = any;
@@ -4266,6 +4289,7 @@ export type PostAgentsAgentIdStreamVNext_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -4387,6 +4411,7 @@ export type PostAgentsAgentIdStreamVnextUi_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -4508,6 +4533,7 @@ export type PostAgentsAgentIdStreamUi_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -12455,6 +12481,7 @@ export type PostAgentsAgentIdGenerateLegacy_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -12574,6 +12601,7 @@ export type PostAgentsAgentIdStreamLegacy_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
     maxSteps?: number | undefined;
     stopWhen?: any | undefined;
@@ -41550,6 +41578,7 @@ export type PostDatasetsDatasetIdExperiments_Body = {
                 status: 'draft' | 'published';
             };
         } | undefined;
+        defaultStatus?: ('draft' | 'published') | undefined;
     } | undefined;
 };
 export type PostDatasetsDatasetIdExperiments_Response = {