@mastra/client-js 1.35.1-alpha.1 → 1.36.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @mastra/client-js
 
+## 1.36.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`723aa54`](https://github.com/mastra-ai/mastra/commit/723aa5437106bdb708ae03c0ef6b77aa11291e73), [`723aa54`](https://github.com/mastra-ai/mastra/commit/723aa5437106bdb708ae03c0ef6b77aa11291e73), [`723aa54`](https://github.com/mastra-ai/mastra/commit/723aa5437106bdb708ae03c0ef6b77aa11291e73)]:
+  - @mastra/core@1.55.0-alpha.3
+
+## 1.36.0-alpha.2
+
+### Minor Changes
+
+- Added the `autoPublish` option to `createStoredAgent()` so SDK users can create an unpublished initial draft. ([#20381](https://github.com/mastra-ai/mastra/pull/20381))
+
+  ```typescript
+  await mastraClient.createStoredAgent({
+    id: 'support-agent',
+    name: 'Support agent',
+    instructions: 'Help customers with support questions.',
+    model: { provider: 'openai', name: 'gpt-5' },
+    autoPublish: false,
+  });
+  ```
+
+### Patch Changes
+
+- Added `TraceInsightResponse` for typed entity-learning trace summaries. ([#20405](https://github.com/mastra-ai/mastra/pull/20405))
+
+  ```ts
+  import type { TraceInsightResponse } from '@mastra/client-js';
+
+  const traceId = (insight: TraceInsightResponse) => insight.traceId;
+  ```
+
+- Added Trace Intelligence progress types and improved the onboarding state with processing progress, clearer copy, accessible markup, mobile polish, and the dedicated documentation link. ([#20401](https://github.com/mastra-ai/mastra/pull/20401))
+
+- Updated dependencies [[`55c9e24`](https://github.com/mastra-ai/mastra/commit/55c9e248c27c1d72b5bb7e94ea6b8a3999eee49f), [`07f5b4b`](https://github.com/mastra-ai/mastra/commit/07f5b4ba9d608d88865030732e580298296adf99)]:
+  - @mastra/core@1.55.0-alpha.2
+
 ## 1.35.1-alpha.1
 
 ### Patch Changes

package/dist/agent-learning.d.ts

@@ -1,4 +1,14 @@
 export type TraceSignalName = 'goal' | 'sentiment' | 'behavior' | 'outcome';
+export type EntityLearningProgressStatus = 'collecting' | 'processing' | 'ready';
+export interface EntityLearningProgressResponse {
+    status: EntityLearningProgressStatus;
+    traceCount: number;
+    signals: Record<TraceSignalName, {
+        generated: number;
+        embedded: number;
+    }>;
+    availableSignals: TraceSignalName[];
+}
 export interface ThemeLearningEntity {
     entityId: string;
     entityType: string;
@@ -148,4 +158,20 @@ export interface NoiseResponse {
         coverage: number;
     };
 }
+export interface TraceInsightSummary {
+    version: string;
+    summary: string;
+    observations: string[];
+    currentTask?: string;
+    degenerate?: boolean;
+    createdAt: string;
+}
+export interface TraceInsightResponse {
+    traceId: string;
+    summary?: TraceInsightSummary;
+    signals: Array<{
+        signalName: TraceSignalName;
+        signalText: string;
+    }>;
+}
 //# sourceMappingURL=agent-learning.d.ts.map

package/dist/agent-learning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-learning.d.ts","sourceRoot":"","sources":["../src/agent-learning.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-learning.d.ts","sourceRoot":"","sources":["../src/agent-learning.ts"],"names":[],"mappings":"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"}

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.35.1-alpha.1"
+  version: "1.36.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.35.1-alpha.1",
+  "version": "1.36.0-alpha.3",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-editor-overview.md

@@ -215,48 +215,50 @@ Version management is available through the server Studio, REST API, the Client
 
 ### Version lifecycle
 
-Each version has one of three statuses:
+Version snapshots don't store a lifecycle status. Instead, the agent or prompt block stores an `activeVersionId` that identifies its published version.
 
-| Status    | Description                                                                         |
-| --------- | ----------------------------------------------------------------------------------- |
-| Draft     | The latest working copy. Every save creates a new draft version.                    |
-| Published | The active version used in production. Only one version can be published at a time. |
-| Archived  | A previous version that's no longer active. You can restore any archived version.   |
+| Term       | Description                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Latest     | The most recently saved version snapshot.                                                                                           |
+| Published  | The version whose ID matches `activeVersionId`. Only one version can be active at a time.                                           |
+| Draft      | The latest version when it differs from the active version. If `activeVersionId` isn't set, the latest version remains unpublished. |
+| Historical | Any other saved version. Historical versions remain available for comparison, direct selection, and restoration.                    |
 
-The typical flow is: Edit the draft and test it, plus then activate it to make it the published version.
+Saving a database-backed resource creates a new latest version. If an active version already exists, it continues to handle requests until you publish the new version. Publishing sets `activeVersionId` to the selected version without deleting or changing the previous active version.
 
-The previously published version becomes archived so you can restore it if needed. You can do this through Studio or programmatically through the API.
-
-This lifecycle makes it safe to experiment. Non-technical team members can iterate on a draft without affecting production traffic, then publish when ready. If something goes wrong, restoring a previous version is a single API call.
+Restoring a historical version copies its configuration into a new draft that remains inactive until you publish it.
 
 ### Version targeting and experimentation
 
-Because every version has a unique ID, you can route different requests to different agent configurations. This opens up several patterns:
+Because every version has a unique ID, you can route different requests to different agent configurations. This supports several patterns:
 
-- **A/B testing**: Split traffic between two published versions and compare performance metrics.
-- **Canary rollouts**: Send a small percentage of requests to a new version before promoting it.
-- **Per-user targeting**: Pin specific users or accounts to a version while others use the default.
-- **Environment separation**: Use the draft version in staging and the published version in production.
+- **A/B testing**: Split traffic between specific version IDs and compare performance metrics.
+- **Canary rollouts**: Send a small percentage of requests to a draft or historical version before publishing it.
+- **Per-user targeting**: Pin specific users or accounts to a version while others use the active version.
+- **Environment separation**: Use the latest version in staging and the active version in production.
 
-Pass a `versionId` or `status` when calling the agent through the Client SDK, server query parameters, or React SDK `requestContext`, and the correct version is loaded automatically.
+Pass a `versionId` or `status` when calling the agent through the Client SDK, server query parameters, or React SDK `requestContext`. A `versionId` selects that exact snapshot, `status: 'draft'` selects the latest snapshot, and `status: 'published'` selects the active snapshot.
 
 ### Version selection
 
-By default, [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) loads the published (active) version of the stored override.
-
-Use a specific version to test a draft before publishing or run an A/B experiment. You can also pin a user to a known-good configuration:
+Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a version selector returns the registered code-defined agent. Pass a selector to apply a published, draft, or specific stored override:
 
 ```typescript
-// Load the published version (default)
-const agent = mastra.getAgentById('support-agent')
+// Load the registered code-defined agent without stored overrides
+const codeAgent = mastra.getAgentById('support-agent')
+
+// Load the active published override
+const publishedAgent = await mastra.getAgentById('support-agent', {
+  status: 'published',
+})
 
-// Load the latest draft
-const agent = mastra.getAgentById('support-agent', {
+// Load the latest override
+const draftAgent = await mastra.getAgentById('support-agent', {
   status: 'draft',
 })
 
 // Load a specific version
-const agent = mastra.getAgentById('support-agent', {
+const versionedAgent = await mastra.getAgentById('support-agent', {
   versionId: 'abc-123',
 })
 ```

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

@@ -727,6 +727,23 @@ const agent = await mastraClient.createStoredAgent({
 })
 ```
 
+By default, `createStoredAgent()` publishes the initial version immediately. Set `autoPublish` to `false` to create an unpublished draft that you can review before calling [`activateVersion()`](#activateversion):
+
+```typescript
+const draft = await mastraClient.createStoredAgent({
+  id: 'draft-agent',
+  name: 'Draft Assistant',
+  instructions: 'You are a helpful assistant.',
+  model: {
+    provider: 'openai',
+    name: 'gpt-5',
+  },
+  autoPublish: false,
+})
+```
+
+Editors configured with the `code` source always publish the initial version because saving writes the agent configuration to the file system.
+
 With all options:
 
 ```typescript