@mastra/client-js 1.22.0-alpha.3 → 1.22.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # @mastra/client-js
 
+## 1.22.0-alpha.5
+
+### Minor Changes
+
+- Added an agent override export API and server-side ownership enforcement. ([#17228](https://github.com/mastra-ai/mastra/pull/17228))
+
+  The server and client now expose an agent override export endpoint so Studio can download an agent's overrides as JSON for review or commit workflows. Saves are enforced server-side against each agent's `editor` config, so only owned fields (instructions, tools, or tool descriptions) are persisted and fields locked by the `editor` config are stripped.
+
+  The system packages response also reports the active editor `source` so clients can render the correct editing experience.
+
+- Added a `PATCH /tool-providers/:providerId/connections/:connectionId` endpoint and matching client SDK method so authors can rename a connection's display label after creation. ([#17249](https://github.com/mastra-ai/mastra/pull/17249))
+
+  **Rename a connection from the client SDK**
+
+  ```ts
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: '…' });
+
+  await client.getToolProvider('composio').updateConnection('auth_abc', {
+    label: 'Work inbox',
+  });
+  ```
+
+  Pass `label: null` (or an empty string) to clear the existing label. Labels are 1–32 characters and accept letters, digits, spaces, underscores, and hyphens (`[A-Za-z0-9 _-]+`).
+
+  **Ownership enforced server-side**
+
+  Non-owners get a 403 unless they hold `tool-providers:admin`. Shared connections are reachable by every author. The label is stored on the connection row itself, so the rename flows to every agent that pins the connection — no per-agent edit needed.
+
+### Patch Changes
+
+- Updated dependencies [[`a18775a`](https://github.com/mastra-ai/mastra/commit/a18775a693172546ee2378d39b67d4e32895b251), [`1baf2d1`](https://github.com/mastra-ai/mastra/commit/1baf2d152c6881338ff8f114633d5316fe13dd15)]:
+  - @mastra/core@1.38.0-alpha.5
+
+## 1.22.0-alpha.4
+
+### Minor Changes
+
+- Added the v1 ToolProvider runtime, server routes, client SDK methods, and editor wiring that power OAuth-backed integrations on stored agents. ([#17248](https://github.com/mastra-ai/mastra/pull/17248))
+
+  **Stored agents can now pin OAuth connections per toolkit**
+
+  A stored agent's config accepts a new `toolProviders` shape that tells the runtime which connection to bind for each toolkit at execution time. Connections can be scoped per-author, shared across an org, or supplied by the caller.
+
+  ```ts
+  {
+    toolProviders: {
+      composio: {
+        connections: {
+          gmail: [{ kind: 'author', toolkit: 'gmail', connectionId: 'auth_abc', scope: 'per-author' }],
+        },
+        tools: {
+          GMAIL_FETCH_EMAILS: { toolkit: 'gmail' },
+        },
+      },
+    },
+  }
+  ```
+
+  **New client SDK surface for managing connections**
+
+  ```ts
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: '…' });
+  const composio = client.toolProvider('composio');
+
+  const { items } = await composio.listConnections({ toolkit: 'gmail' });
+  await composio.disconnectConnection('auth_abc');
+  ```
+
+  **New `ToolProvider` interface for custom providers**
+
+  Providers implement a VNext surface (`listToolkitsVNext`, `listToolsVNext`, `resolveToolsVNext`) plus the auth round-trip (`authorize`, `getAuthStatus`, `listConnections`, `disconnectConnection`, `listConnectionFields`, `health`). The Composio provider has been rewritten on this surface; the older catalog methods remain as `@deprecated` shims for back-compat.
+
+  Connections list responses use `page`/`perPage` pagination, matching the rest of the server surface.
+
+  Both stored agents (`editor.agent.getById(...)`) and code-defined agents with stored overrides (`editor.agent.applyStoredOverrides(...)`) resolve `toolProviders` at request time, merging provider-resolved tools alongside code/registry/MCP/integration tools.
+
+  Stored agents that don't set `toolProviders` continue to work unchanged. The Studio/Builder UI ships separately.
+
+### Patch Changes
+
+- Hardened v1 ToolProvider connection routes and SDK forwarding. ([#17248](https://github.com/mastra-ai/mastra/pull/17248))
+
+  **Fail closed on unknown `connectionId`**
+
+  `DELETE /tool-providers/:providerId/connections/:connectionId` and
+  `GET …/usage` now return `403` when storage is configured but no persisted
+  row matches the supplied `connectionId` and the caller isn't an admin.
+  Previously these routes fell through to the caller's own `authorId`, which
+  let non-admin callers probe (and trigger provider-side `revokeConnection`
+  for) IDs that didn't belong to them.
+
+  **Aligned authorize label validation with stored label rules**
+
+  `POST /tool-providers/:providerId/authorize` now enforces the same label
+  rules the stored `toolProviders` config uses (`min(1)`, `max(32)`,
+  `/^[A-Za-z0-9 _-]+$/`). Labels that pass `authorize` are now guaranteed to
+  pass downstream stored-agent validation.
+
+  **SDK forwards `toolkit` on connection-scoped operations**
+
+  `@mastra/client-js`:
+
+  ```ts
+  await client.toolProviders.get('composio').disconnectConnection('ca_xxx', {
+    toolkit: 'gmail',
+    force: true,
+  });
+
+  const usage = await client.toolProviders.get('composio').getConnectionUsage('ca_xxx', { toolkit: 'gmail' });
+  ```
+
+  `disconnectConnection` now forwards `params.toolkit` (previously dropped)
+  and `getConnectionUsage` accepts an optional `{ toolkit }` parameter so
+  toolkit-scoped connection lookups disambiguate correctly server-side.
+
+- Improved observability and error isolation in the v1 ToolProvider runtime. ([#17248](https://github.com/mastra-ai/mastra/pull/17248))
+
+  **Better visibility into connection-scope misconfiguration**
+
+  When an agent runs with a stored ToolProvider connection whose scope cannot be resolved from the request context, the runtime now logs a one-shot warning and falls back to a shared bucket instead of silently routing every caller to the same OAuth account. Multi-tenant deployments get a clear signal when their identity wiring isn't reaching the runtime.
+
+  **One bad toolkit no longer disables sibling providers**
+
+  If a provider returns more connections for a toolkit than its declared capabilities allow, the runtime now logs and skips that toolkit instead of throwing. Other providers and other toolkits on the same agent continue to resolve normally.
+
+- Updated dependencies [[`50ed00c`](https://github.com/mastra-ai/mastra/commit/50ed00caa914a85969b33de83f26b48e328ef641), [`9283971`](https://github.com/mastra-ai/mastra/commit/928397157009b4aef4d5fdf3a0a273cb371beb55), [`0bf2d93`](https://github.com/mastra-ai/mastra/commit/0bf2d932d20e2936f2d9abb8c0a86e24fbc97ec6), [`94dfef6`](https://github.com/mastra-ai/mastra/commit/94dfef6e2bf19a88467ea3940afcbce88a433f0f), [`a122f79`](https://github.com/mastra-ai/mastra/commit/a122f79427ae225ec79c7b2ed46278da48d04b17), [`4c02027`](https://github.com/mastra-ai/mastra/commit/4c020277235eaa6b1dc957c90ad0639eef213992), [`6855012`](https://github.com/mastra-ai/mastra/commit/685501247cc4717506f3e89beed03509d63a5370), [`7fef31c`](https://github.com/mastra-ai/mastra/commit/7fef31c0d2a6d362a43a647a8a4f6ab893758a23), [`7fef31c`](https://github.com/mastra-ai/mastra/commit/7fef31c0d2a6d362a43a647a8a4f6ab893758a23)]:
+  - @mastra/core@1.38.0-alpha.4
+
 ## 1.22.0-alpha.3
 
 ### Minor 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.22.0-alpha.3"
+  version: "1.22.0-alpha.5"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.0-alpha.3",
+  "version": "1.22.0-alpha.5",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

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

@@ -66,6 +66,41 @@ Once registered, you can manage agents through [Studio](https://mastra.ai/docs/s
 
 > **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
+## Code and database sources
+
+The editor stores agent overrides in one of two sources, set with the `source` option on `MastraEditor`:
+
+| Source         | Where overrides live                                      | Studio actions                                           |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------- |
+| `db` (default) | The configured storage backend.                           | Save and publish drafts.                                 |
+| `code`         | Per-agent JSON files on disk, tracked in your repository. | Download the override file or save it to the filesystem. |
+
+The default `db` source is best when non-developers iterate through Studio and you want versioning, drafts, and runtime version targeting. The `code` source is best when overrides should live in your repository alongside the rest of your code, reviewed through pull requests and deployed with your application.
+
+To use the code source, set `source: 'code'`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: {
+    /* your existing agents */
+  },
+  editor: new MastraEditor({
+    source: 'code',
+  }),
+})
+```
+
+When `source` is `'code'`, the editor writes each override to a deterministic JSON file under `./mastra/editor/agents/<agentId>.json`. Set `codePath` to change the directory. Because the files are deterministic, every save produces a clean diff you can commit and review.
+
+### Versioning with the code source
+
+The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file appears as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
+
+This means versions and rollbacks are managed through Git rather than through draft and publish actions.
+
 ## 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.
@@ -114,15 +149,16 @@ The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and
 
 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.    |
+| 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.                                           |
+| `POST`   | `/stored/agents/:storedAgentId/export` | Export a stored agent's override as a deterministic JSON config. |
 
-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.
+The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, and `client.getStoredAgent(id).export()`. 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
 
@@ -149,6 +185,32 @@ When you edit a code-defined agent through the editor, only specific fields can
 
 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.
 
+### Controlling what is editable
+
+Use the `editor` field on a code-defined agent to control which fields the editor can override. This lets you keep some fields code-owned while allowing edits to others:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5.4',
+  editor: { instructions: true, tools: { description: true } },
+})
+```
+
+The `editor` field accepts these shapes:
+
+| Value                              | Result                                                     |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Omitted                            | Instructions and tools are editable.                       |
+| `false`                            | Nothing is editable. The agent is locked.                  |
+| `{ instructions: true }`           | Instructions are editable.                                 |
+| `{ tools: true }`                  | Tool membership and descriptions are editable.             |
+| `{ tools: { description: true } }` | Only tool descriptions are editable. Membership is locked. |
+
+When a field is owned by code, Studio shows it as read-only and the server strips it from saved overrides, so the stored config only contains the fields you allow. See the [`editor` overrides reference](https://mastra.ai/reference/agents/agent) for the full type.
+
 ## 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.

package/dist/index.cjs

@@ -4710,6 +4710,15 @@ var StoredAgent = class extends BaseResource {
       }
     );
   }
+  /**
+   * Exports deterministic JSON for this agent without mutating storage.
+   */
+  export(params) {
+    return this.request(`/stored/agents/${encodeURIComponent(this.storedAgentId)}/export`, {
+      method: "POST",
+      body: params
+    });
+  }
   /**
    * Deletes the stored agent
    * @param requestContext - Optional request context to pass as query parameter
@@ -5243,16 +5252,13 @@ var ToolProvider = class extends BaseResource {
   }
   providerId;
   /**
-   * Lists available toolkits from this provider
-   * @returns Promise containing list of toolkits
+   * Lists available toolkits from this provider.
    */
   listToolkits() {
     return this.request(`/tool-providers/${encodeURIComponent(this.providerId)}/toolkits`);
   }
   /**
-   * Lists available tools from this provider, with optional filtering
-   * @param params - Optional filtering and pagination parameters
-   * @returns Promise containing list of tools
+   * Lists available tools from this provider, with optional filtering.
    */
   listTools(params) {
     const searchParams = new URLSearchParams();
@@ -5274,15 +5280,139 @@ var ToolProvider = class extends BaseResource {
     );
   }
   /**
-   * Gets the input schema for a specific tool
-   * @param toolSlug - The slug of the tool
-   * @returns Promise containing the tool's JSON schema
+   * Gets the input schema for a specific tool.
    */
   getToolSchema(toolSlug) {
     return this.request(
       `/tool-providers/${encodeURIComponent(this.providerId)}/tools/${encodeURIComponent(toolSlug)}/schema`
     );
   }
+  /**
+   * Starts an OAuth flow for a (toolkit, connectionId) pair. Returns a
+   * redirect URL and an opaque auth handle to poll with `getAuthStatus`.
+   */
+  authorize(params) {
+    return this.request(`/tool-providers/${encodeURIComponent(this.providerId)}/authorize`, {
+      method: "POST",
+      body: params
+    });
+  }
+  /**
+   * Polls the OAuth flow status for an outstanding authorize call.
+   */
+  getAuthStatus(authId) {
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/auth-status/${encodeURIComponent(authId)}`
+    );
+  }
+  /**
+   * Batch-checks whether a set of (connectionId, toolkit) tuples are
+   * currently connected.
+   */
+  getConnectionStatus(params) {
+    return this.request(`/tool-providers/${encodeURIComponent(this.providerId)}/connection-status`, {
+      method: "POST",
+      body: params
+    });
+  }
+  /**
+   * Lists existing provider connections, scoped to a toolkit.
+   *
+   * Default: the connection owner is resolved server-side from the request's
+   * auth context. Admin callers (with `tool-providers:admin` permission) may
+   * pass `authorId` to target a specific author, or omit it to receive
+   * connections across all authors known to `tool_provider_connections` for
+   * this provider/toolkit. Pagination is page-based via `page` (1-indexed)
+   * and `perPage` (default 50, max 200).
+   */
+  listConnections(params) {
+    const searchParams = new URLSearchParams();
+    searchParams.set("toolkit", params.toolkit);
+    if (params.authorId) {
+      searchParams.set("authorId", params.authorId);
+    }
+    if (params.page !== void 0 && params.page !== null) {
+      searchParams.set("page", String(params.page));
+    }
+    if (params.perPage !== void 0 && params.perPage !== null) {
+      searchParams.set("perPage", String(params.perPage));
+    }
+    if (params.scope) {
+      searchParams.set("scope", params.scope);
+    }
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/connections?${searchParams.toString()}`
+    );
+  }
+  /**
+   * Lists provider-specific fields the picker should collect before
+   * initiating a new connection (e.g. Confluence subdomain). Most toolkits
+   * return an empty array.
+   */
+  listConnectionFields(params) {
+    const searchParams = new URLSearchParams();
+    searchParams.set("toolkit", params.toolkit);
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/connection-fields?${searchParams.toString()}`
+    );
+  }
+  /**
+   * Disconnects (revokes + deletes) a persisted connection.
+   *
+   * Without `force: true` the server refuses if any agent still pins the
+   * connection. With `force: true` the provider-side revoke is best-effort
+   * (errors are tolerated) and the local row is always removed.
+   */
+  disconnectConnection(connectionId, params) {
+    const searchParams = new URLSearchParams();
+    if (params?.toolkit) {
+      searchParams.set("toolkit", params.toolkit);
+    }
+    if (params?.force) {
+      searchParams.set("force", "true");
+    }
+    const queryString = searchParams.toString();
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/connections/${encodeURIComponent(connectionId)}${queryString ? `?${queryString}` : ""}`,
+      {
+        method: "DELETE"
+      }
+    );
+  }
+  /**
+   * Updates the persisted display label on a connection row. Pass `label: null`
+   * (or an empty string) to clear the existing label. Only the connection owner
+   * or an admin may rename, unless the row is `scope: 'shared'`.
+   */
+  updateConnection(connectionId, params) {
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/connections/${encodeURIComponent(connectionId)}`,
+      {
+        method: "PATCH",
+        body: params
+      }
+    );
+  }
+  /**
+   * Lists the agents that currently pin a given connection. Used by the
+   * picker to warn the user before disconnecting a shared account.
+   */
+  getConnectionUsage(connectionId, params) {
+    const searchParams = new URLSearchParams();
+    if (params?.toolkit) {
+      searchParams.set("toolkit", params.toolkit);
+    }
+    const queryString = searchParams.toString();
+    return this.request(
+      `/tool-providers/${encodeURIComponent(this.providerId)}/connections/${encodeURIComponent(connectionId)}/usage${queryString ? `?${queryString}` : ""}`
+    );
+  }
+  /**
+   * Returns provider-level health (config, reachability, etc.).
+   */
+  getHealth() {
+    return this.request(`/tool-providers/${encodeURIComponent(this.providerId)}/health`);
+  }
 };
 
 // src/resources/processor-provider.ts