@mastra/client-js 1.13.2-alpha.1 → 1.13.3-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/client-js
 
+## 1.13.3-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`ef94400`](https://github.com/mastra-ai/mastra/commit/ef9440049402596b31f2ab976c5e4508f6cb6c91)]:
+  - @mastra/core@1.24.1-alpha.0
+
+## 1.13.2
+
+### Patch Changes
+
+- Fixed the client JS Responses types to allow omitting the model override. ([#15140](https://github.com/mastra-ai/mastra/pull/15140))
+
+- Updated dependencies [[`8db7663`](https://github.com/mastra-ai/mastra/commit/8db7663c9a9c735828094c359d2e327fd4f8fba3), [`153e864`](https://github.com/mastra-ai/mastra/commit/153e86476b425db7cd0dc8490050096e92964a38), [`715710d`](https://github.com/mastra-ai/mastra/commit/715710d12fa47cf88e09d41f13843eddc29327b0), [`378c6c4`](https://github.com/mastra-ai/mastra/commit/378c6c4755726e8d8cf83a14809b350b90d46c62), [`9f91fd5`](https://github.com/mastra-ai/mastra/commit/9f91fd538ab2a44f8cc740bcad8e51205f74fbea), [`ba6fa9c`](https://github.com/mastra-ai/mastra/commit/ba6fa9cc0f3e1912c49fd70d4c3bb8c44903ddaa)]:
+  - @mastra/core@1.24.0
+
 ## 1.13.2-alpha.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.13.2-alpha.1"
+  version: "1.13.3-alpha.0"
 ---
 
 ## When to use
@@ -16,6 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
+- [Editor overview](references/docs-editor-overview.md) - Let non-technical team members iterate on agents, version every change, and run experiments without redeploying.
 - [Auth0](references/docs-server-auth-auth0.md) - Documentation for the @mastra/auth-auth0 package, which authenticates Mastra applications using Auth0 authentication.
 - [Clerk](references/docs-server-auth-clerk.md) - Documentation for the `@mastra/auth-clerk` package, which authenticates Mastra applications using Clerk authentication.
 - [Firebase](references/docs-server-auth-firebase.md) - Documentation for the `@mastra/auth-firebase` package, which authenticates Mastra applications using Firebase Authentication.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.13.2-alpha.1",
+  "version": "1.13.3-alpha.0",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

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

@@ -0,0 +1,221 @@
+# Editor overview
+
+The editor is a CMS-style system that separates agent configuration from code. Subject-matter experts, prompt engineers, and product teams can iterate on agents directly while developers keep the codebase stable.
+
+The editor manages two types of resources alongside agents:
+
+- [**Prompts**](https://mastra.ai/docs/editor/prompts): Reusable, versioned instruction templates with template variables and display conditions.
+- [**Tools**](https://mastra.ai/docs/editor/tools): Add tools from integration providers, MCP servers, and override tool descriptions at runtime.
+
+## When to use the editor
+
+Use the editor when you want to:
+
+- **Let non-developers iterate**: Give subject-matter experts and prompt engineers a way to tune agent behavior without touching code or waiting for deploys.
+- **Version everything**: Every save creates a snapshot so you can compare changes, roll back instantly, and audit what changed and when.
+- **Run experiments**: Route different users or requests to different agent versions for A/B testing, canary rollouts, or prompt experimentation.
+- **Target specific versions**: Pin a version per request, per user, or per environment so production stays stable while new versions are tested.
+- **Manage tools at runtime**: Add integration tools from Composio or Arcade, or connect MCP servers, without updating code.
+- **Override code agents**: Change the instructions, tools, or variables of a code-defined agent while keeping the original code as the baseline.
+
+For building agents entirely in code, see the [Agents overview](https://mastra.ai/docs/agents/overview).
+
+## Quickstart
+
+Add `@mastra/editor` to your project:
+
+**npm**:
+
+```bash
+npm install @mastra/editor
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/editor
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/editor
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/editor
+```
+
+Pass a `MastraEditor` instance to your Mastra configuration with your existing agents:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: {
+    /* your existing agents */
+  },
+  editor: new MastraEditor(),
+})
+```
+
+Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK.
+
+> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
+
+## Studio
+
+Go to the **Agents** tab in Studio and select an agent to edit. Select the **Editor** tab. You'll be taken to the editor interface, where you can modify the agent's instructions, tools, and variables.
+
+Modify the system prompt and save a new draft version. Afterwards, publish the draft to make it the active version.
+
+## Programmatic control
+
+Everything you can do in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor). This is useful for scripting bulk updates, seeding stored configurations from code, or building automation that tunes agents based on evaluation results.
+
+Call `mastra.getEditor()` from anywhere you have access to the `Mastra` instance. It returns the `MastraEditor` instance you registered, with namespaces for each resource type:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()
+if (!editor) throw new Error('Editor is not registered on Mastra')
+
+// Create a stored agent override for an existing code-defined agent
+await editor.agent.create({
+  id: 'support-agent',
+  instructions: 'You are a friendly support agent for Acme Inc.',
+  tools: {
+    search_kb: { description: 'Search the Acme knowledge base' },
+  },
+})
+```
+
+Use `editor.agent.update()` to change an existing stored configuration. Every update creates a new draft version automatically:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.update({
+  id: 'support-agent',
+  instructions:
+    "You are a friendly support agent for Acme Inc. Always respond in the user's language.",
+})
+```
+
+The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and `delete`. The `editor.prompt` namespace exposes the same CRUD methods for prompt blocks. See [Prompts](https://mastra.ai/docs/editor/prompts) for examples.
+
+### Server endpoints
+
+The same operations are available over HTTP through the Mastra server. Use these when you want to manage stored agents from a separate service or from a non-TypeScript client:
+
+| Method   | Path                            | Description               |
+| -------- | ------------------------------- | ------------------------- |
+| `GET`    | `/stored/agents`                | List all stored agents.   |
+| `POST`   | `/stored/agents`                | Create a stored agent.    |
+| `GET`    | `/stored/agents/:storedAgentId` | Get a stored agent by ID. |
+| `PATCH`  | `/stored/agents/:storedAgentId` | Update a stored agent.    |
+| `DELETE` | `/stored/agents/:storedAgentId` | Delete a stored agent.    |
+
+The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, and `client.getStoredAgent()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
+
+### Automated experimentation
+
+Because stored agents are just data, you can build automation loops that tune agents without human involvement. A common pattern is to pair the editor API with [datasets](https://mastra.ai/docs/evals/datasets/overview) and [experiments](https://mastra.ai/docs/evals/datasets/running-experiments):
+
+- Run a dataset through the current version of an agent and score the results.
+- Have another agent read the failing cases and propose changes to the instructions or tools.
+- Apply those changes with `editor.agent.update()` to create a new draft.
+- Re-run the experiment against the draft and compare scores to the baseline.
+- Promote the draft to the published version when the scores improve.
+
+This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested.
+
+> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
+
+## What can be overridden
+
+When you edit a code-defined agent through the editor, only specific fields can be changed:
+
+| Field        | Description                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------- |
+| Instructions | Replace or extend the agent's system prompt using [prompt blocks](https://mastra.ai/docs/editor/prompts).     |
+| Tools        | Add tools from the tool registry, integration providers, or MCP clients. Code-defined tools remain available. |
+
+Fields like the agent's `id`, `name`, and `model` come from your code and can't be changed through the editor for code-defined agents. The variables are also read-only.
+
+## Versioning
+
+Every time you save changes to an agent or prompt block, a new version snapshot is created. Versions give you a full history of your agent's configuration. You can roll back to any previous state, compare what changed between two snapshots, and target specific versions per request for A/B testing or gradual rollouts.
+
+Version management is available through the server Studio, REST API, the Client SDK, and the React SDK. See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for endpoints, SDK methods, and code examples.
+
+### Version lifecycle
+
+Each version has one of three statuses:
+
+| 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 is no longer active. You can restore any archived version.  |
+
+The typical flow is: Edit the draft, test it, then activate it to make it the published 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.
+
+### 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:
+
+- **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.
+
+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.
+
+### Version selection
+
+By default, [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) loads the published (active) version of the stored override. You can request a specific version, which is useful for testing a draft before publishing, running A/B experiments, or pinning a user to a known-good configuration:
+
+```typescript
+// Load the published version (default)
+const agent = mastra.getAgentById('support-agent')
+
+// Load the latest draft
+const agent = mastra.getAgentById('support-agent', {
+  status: 'draft',
+})
+
+// Load a specific version
+const agent = mastra.getAgentById('support-agent', {
+  versionId: 'abc-123',
+})
+```
+
+When calling the agent through the Mastra server, pass version parameters as query strings:
+
+```bash
+# Published version (default)
+curl http://localhost:4111/agents/support-agent
+
+# Latest draft
+curl http://localhost:4111/agents/support-agent?status=draft
+
+# Specific version
+curl http://localhost:4111/agents/support-agent?versionId=abc-123
+```
+
+See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for API methods.
+
+## Next steps
+
+- Set up [prompts](https://mastra.ai/docs/editor/prompts) to build reusable instruction templates.
+- Add [tools](https://mastra.ai/docs/editor/tools) from integration providers and MCP servers.
+- Explore the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.

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

@@ -439,4 +439,140 @@ Delete a stored agent:
 ```typescript
 const result = await storedAgent.delete()
 console.log(result.success) // true
+```
+
+## Version management
+
+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.
+
+### Server endpoints
+
+Version management is also available through the stored agents REST API:
+
+| Method   | Endpoint                                                     | Description                             |
+| -------- | ------------------------------------------------------------ | --------------------------------------- |
+| `GET`    | `/stored/agents/:agentId/versions`                           | List all versions.                      |
+| `POST`   | `/stored/agents/:agentId/versions`                           | Create a new version.                   |
+| `GET`    | `/stored/agents/:agentId/versions/:versionId`                | Get a specific version.                 |
+| `POST`   | `/stored/agents/:agentId/versions/:versionId/activate`       | Set the active version.                 |
+| `POST`   | `/stored/agents/:agentId/versions/:versionId/restore`        | Restore a version (creates a new copy). |
+| `DELETE` | `/stored/agents/:agentId/versions/:versionId`                | Delete a version.                       |
+| `GET`    | `/stored/agents/:agentId/versions/compare?from=<id>&to=<id>` | Compare two versions.                   |
+
+### Getting an agent with a specific version
+
+Pass a version identifier when getting an agent:
+
+```typescript
+// Load the published version (default)
+const agent = mastraClient.getAgent('support-agent')
+
+// Load the latest draft
+const draftAgent = mastraClient.getAgent('support-agent', { status: 'draft' })
+
+// Load a specific version
+const versionedAgent = mastraClient.getAgent('support-agent', { versionId: 'abc-123' })
+```
+
+For stored agents, pass a status option to `details()`:
+
+```typescript
+const storedAgent = mastraClient.getStoredAgent('my-agent')
+const draft = await storedAgent.details(undefined, { status: 'draft' })
+```
+
+### `listVersions()`
+
+List all versions for an agent:
+
+```typescript
+const versions = await agent.listVersions()
+console.log(versions.items) // Array of version snapshots
+console.log(versions.total)
+```
+
+With pagination and sorting:
+
+```typescript
+const versions = await agent.listVersions({
+  page: 0,
+  perPage: 10,
+  orderBy: {
+    field: 'createdAt',
+    direction: 'DESC',
+  },
+})
+```
+
+### `createVersion()`
+
+Create a new version snapshot:
+
+```typescript
+const version = await agent.createVersion({
+  changeMessage: 'Updated tone to be more friendly',
+})
+```
+
+### `getVersion()`
+
+Get a specific version by ID:
+
+```typescript
+const version = await agent.getVersion('version-123')
+console.log(version.versionNumber)
+console.log(version.changedFields)
+console.log(version.createdAt)
+```
+
+### `activateVersion()`
+
+Set a version as the active published version:
+
+```typescript
+await agent.activateVersion('version-123')
+```
+
+### `restoreVersion()`
+
+Restore a previous version by creating a new version with the same configuration:
+
+```typescript
+await agent.restoreVersion('version-456')
+```
+
+### `deleteVersion()`
+
+Delete a version:
+
+```typescript
+await agent.deleteVersion('version-789')
+```
+
+### `compareVersions()`
+
+Compare two versions and return their differences:
+
+```typescript
+const diff = await agent.compareVersions('version-123', 'version-456')
+console.log(diff.changes) // Fields that changed between versions
+```
+
+### React SDK
+
+In the React SDK, pass an `agentVersionId` through `requestContext` when using the `useChat` hook:
+
+```typescript
+import { useChat } from '@mastra/react'
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    agentId: 'support-agent',
+    requestContext: {
+      agentVersionId: 'abc-123',
+    },
+  })
+
+  // ... render chat UI
+}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/client-js",
-  "version": "1.13.2-alpha.1",
+  "version": "1.13.3-alpha.0",
   "description": "The official TypeScript library for the Mastra Client API",
   "author": "",
   "type": "module",
@@ -37,8 +37,8 @@
     "@ai-sdk/ui-utils": "^1.2.11",
     "@lukeed/uuid": "^2.0.1",
     "json-schema": "^0.4.0",
-    "@mastra/core": "1.24.0-alpha.1",
-    "@mastra/schema-compat": "1.2.7"
+    "@mastra/schema-compat": "1.2.7",
+    "@mastra/core": "1.24.1-alpha.0"
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
@@ -53,10 +53,10 @@
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
     "zod": "^4.3.6",
-    "@internal/ai-sdk-v4": "0.0.27",
-    "@internal/ai-sdk-v5": "0.0.27",
-    "@internal/types-builder": "0.0.55",
-    "@internal/lint": "0.0.80"
+    "@internal/ai-sdk-v4": "0.0.28",
+    "@internal/lint": "0.0.81",
+    "@internal/ai-sdk-v5": "0.0.28",
+    "@internal/types-builder": "0.0.56"
   },
   "engines": {
     "node": ">=22.13.0"