@mastra/client-js 1.24.0-alpha.4 → 1.25.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @mastra/client-js
 
+## 1.25.0
+
+### Minor Changes
+
+- Added server and client APIs for source-backed stored agent workflows. ([#17583](https://github.com/mastra-ai/mastra/pull/17583))
+
+  The stored agent API can now report editor source capabilities, export owned agent override JSON, and open provider-backed change requests from the server. The client SDK exposes matching methods so Studio and other clients can use the same stored-agent workflow without calling a source provider directly.
+
+  ```ts
+  const storedAgent = client.getStoredAgent('weather-agent');
+  const exported = await storedAgent.export({ instructions: '...' });
+  await storedAgent.openChangeRequest({
+    instructions: '...',
+    changeMessage: 'Tune weather instructions',
+  });
+  ```
+
+### Patch Changes
+
+- Fixed client tool model output so multimodal content uses the AI SDK media format. ([#17825](https://github.com/mastra-ai/mastra/pull/17825))
+
+- Republished clean patch versions after compromised npm releases were published outside of the trusted release workflow. ([#18049](https://github.com/mastra-ai/mastra/pull/18049))
+
+  These packages must be released as clean versions higher than the compromised versions currently present on npm so semver ranges resolve to trusted tarballs.
+
+- Fixed client tools ignoring `toModelOutput`. Client tools defined with a `toModelOutput` function now send their transformed output to the model, the same way server tools do. Previously the mapping was silently skipped for client tools, so multimodal tool results (for example screenshots returned as images) reached the model as stringified JSON instead of native image content. The raw tool result is still preserved for storage and application logic; only what the model sees changes. Fixes https://github.com/mastra-ai/mastra/issues/17792 ([#17825](https://github.com/mastra-ai/mastra/pull/17825))
+
+- Updated dependencies [[`de66bb0`](https://github.com/mastra-ai/mastra/commit/de66bb040570444c702ce4d8e1e228a5de2949cb), [`67bf8e2`](https://github.com/mastra-ai/mastra/commit/67bf8e206dfe583954d96015cf0d09f7ac50e45f), [`8216d05`](https://github.com/mastra-ai/mastra/commit/8216d0528d866eb9a07f5d4c87ea3bb1e1139b45), [`d18b23c`](https://github.com/mastra-ai/mastra/commit/d18b23c5e29dfc381e73e3c51fcf6c779afd1823), [`5eb94eb`](https://github.com/mastra-ai/mastra/commit/5eb94ebcf66d4e28c9e26d5821ac93379bab20a0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`f9ee2ac`](https://github.com/mastra-ai/mastra/commit/f9ee2ac661af584e61bc063ac208c9035cd752ef), [`c853d53`](https://github.com/mastra-ai/mastra/commit/c853d535d2df84ab89db1adb4c28900c54c9a2d2), [`d8df1f8`](https://github.com/mastra-ai/mastra/commit/d8df1f8e947e1966c9d4e54713df56d0d0d65226), [`9192ddb`](https://github.com/mastra-ai/mastra/commit/9192ddbced8949113b30de444cbe763f075b59f5), [`ae96523`](https://github.com/mastra-ai/mastra/commit/ae965231f562d9766b0c90c49a69fc68acaa031c), [`17d5a92`](https://github.com/mastra-ai/mastra/commit/17d5a9211aa293b4d4418de3de70dc0394d58101), [`5573693`](https://github.com/mastra-ai/mastra/commit/5573693b589822250e20dfe6cf66e9ff3bc96da8), [`ec4da8a`](https://github.com/mastra-ai/mastra/commit/ec4da8a09e0d2ab452c6ee2c786042ea826b77e5), [`adc44e1`](https://github.com/mastra-ai/mastra/commit/adc44e13c7e570b91e86b20ea7556e61d819db31), [`ed346c0`](https://github.com/mastra-ai/mastra/commit/ed346c0bee2d8496690a4e538bfba1e46894660f), [`9b1adf7`](https://github.com/mastra-ai/mastra/commit/9b1adf7f39943c869182106bc4016e793b3304ac), [`c9ce1b2`](https://github.com/mastra-ai/mastra/commit/c9ce1b28d10871110648f9d7b6d76e880b9fa999), [`3ef01fd`](https://github.com/mastra-ai/mastra/commit/3ef01fd130b53d5bd4f828beb174e516a2eb1158), [`245a9a3`](https://github.com/mastra-ai/mastra/commit/245a9a315705fce17ddd980f78a92504b6615c4a), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`38b5de8`](https://github.com/mastra-ai/mastra/commit/38b5de8e5d1d41a69522addf53d96f4b3a1d5bf0), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`dd6a66e`](https://github.com/mastra-ai/mastra/commit/dd6a66ea0b32e0dea8059aec6b35d151e2c87dc4), [`d785c59`](https://github.com/mastra-ai/mastra/commit/d785c593b67fcb4cdc4fab9fdbde5f3b7665efc0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`8b984f4`](https://github.com/mastra-ai/mastra/commit/8b984f4361c202270ceb69257185c4756c9a7c56), [`bf08402`](https://github.com/mastra-ai/mastra/commit/bf084022374fa5d06ca70ed67a86dd64e379071b), [`81fe587`](https://github.com/mastra-ai/mastra/commit/81fe587275035715c1720ddf3fee0505cf053036), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`403c438`](https://github.com/mastra-ai/mastra/commit/403c438e417278989ce247233d2c465b8d902cdd), [`f8ba195`](https://github.com/mastra-ai/mastra/commit/f8ba1954e27ee2b20586cc6cd9cf13c002c232f2)]:
+  - @mastra/core@1.43.0
+  - @mastra/schema-compat@1.2.12
+
+## 1.24.0
+
+### Minor Changes
+
+- Add server endpoints so Studio can resolve agent-builder model availability and auth permission patterns without importing server-only EE code in the browser: ([#17489](https://github.com/mastra-ai/mastra/pull/17489))
+  - `GET /editor/builder/models/available` returns the provider/model list already filtered by the active builder model policy (`requiresAuth: true`, `stored-agents:read`).
+  - `GET /auth/permission-patterns` returns the valid permission-pattern strings. It is gated by `requiresAuth: true` with no finer-grained permission: the response is the non-sensitive route-permission vocabulary that every authenticated user needs to gate their own sidebar/redirects, and there is no narrower permission that fits.
+
+  `@mastra/client-js` gains `getBuilderAvailableModels()` and `getPermissionPatterns()` to consume these endpoints.
+
+  ```ts
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:4111' });
+
+  const { providers } = await client.getBuilderAvailableModels();
+  const { patterns } = await client.getPermissionPatterns();
+  ```
+
+- **Added** optional `author` field on `StoredAgentResponse` so consumers can render the resolved author (name, email, avatar) returned by stored-agent list and detail endpoints. ([#17205](https://github.com/mastra-ai/mastra/pull/17205))
+
+### Patch Changes
+
+- **Added** author enrichment to the stored-agents list and get handlers. When an auth provider is configured, each agent record now includes a resolved `author` object alongside the existing `authorId`: ([#17205](https://github.com/mastra-ai/mastra/pull/17205))
+
+  ```ts
+  {
+    id: 'agent_…',
+    authorId: 'user_…',
+   id, name?, email?, avatarUrl? } // new, optional
+    // …
+  }
+  ```
+
+  Lookups are deduplicated per request and use the provider's `getUsers` batch method when available, falling back to per-id `getUser` calls otherwise. The field is omitted when no auth provider is configured or the ID can't be resolved, so existing clients keep working unchanged.
+
+- Fixed subscribed client tool continuations so browser-provided tool results keep their original inputs and client tools remain available across continuation runs. ([#17603](https://github.com/mastra-ai/mastra/pull/17603))
+
+- **Added** optional `getUsers(userIds)` batch lookup method to `IUserProvider`. Auth providers can implement it to resolve multiple users in a single call; providers that don't implement it continue to work via per-id `getUser` fallback. ([#17205](https://github.com/mastra-ai/mastra/pull/17205))
+
+  ```ts
+  // optional batch lookup, returns results positionally aligned to userIds
+  const users = await provider.getUsers?.(['u_1', 'u_2', 'u_3']);
+  ```
+
+- Added agent memory-support metadata to the agents API and client types. ([#17581](https://github.com/mastra-ai/mastra/pull/17581))
+
+- Added metric time series response type exports for client SDK consumers. ([#17686](https://github.com/mastra-ai/mastra/pull/17686))
+
+- Fixed subscribed client-tool continuations so client tools remain available across multiple continuation runs. ([#17593](https://github.com/mastra-ai/mastra/pull/17593))
+
+- Updated dependencies [[`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`053735a`](https://github.com/mastra-ai/mastra/commit/053735a75c2c18e23ce34d9468007efa4a45f4c4), [`306909a`](https://github.com/mastra-ai/mastra/commit/306909a693de77d709b38706e2673c9547d24a28), [`5191af8`](https://github.com/mastra-ai/mastra/commit/5191af80c799eea25357c545fc05d91b3883531d), [`43bd3d4`](https://github.com/mastra-ai/mastra/commit/43bd3d421987463fdf35386a45199c49499ed069), [`e6fa79e`](https://github.com/mastra-ai/mastra/commit/e6fa79ec72a2ddffdd25e85270398951e9d552a4), [`904bcdf`](https://github.com/mastra-ai/mastra/commit/904bcdf7b8004aa7be823f9f70ca63580e47e470), [`7f5ee1d`](https://github.com/mastra-ai/mastra/commit/7f5ee1dca46daee8d2817f2ebe49e6335da81956), [`1e9aab5`](https://github.com/mastra-ai/mastra/commit/1e9aab50ff11e6e88fde4d7cbf512c44a9fe8d61), [`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`e9be4e7`](https://github.com/mastra-ai/mastra/commit/e9be4e747ec3d8b65548bff92f9377db06105376), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`d53cfc2`](https://github.com/mastra-ai/mastra/commit/d53cfc2c7f8d78343a4aa84ec4e129ba25f3325e), [`65799d4`](https://github.com/mastra-ai/mastra/commit/65799d4d549e5ebb9c848fbe3f51ac090f64becf), [`c268c89`](https://github.com/mastra-ai/mastra/commit/c268c89f4c63a93ee474d3cffdf3ea60bf00d4f2), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`014e00f`](https://github.com/mastra-ai/mastra/commit/014e00f2b3a597a016b72f9901c6ab27d491f822), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`d468acb`](https://github.com/mastra-ai/mastra/commit/d468acb07aec1bb19a2cb0ada8042b05b46746b2), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`0c72f03`](https://github.com/mastra-ai/mastra/commit/0c72f032abb13254df5a7856d64be2f207b8006d), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`3b45ea9`](https://github.com/mastra-ai/mastra/commit/3b45ea95015557a6cb9d70dc5252af54ab1b78ac), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`f084be1`](https://github.com/mastra-ai/mastra/commit/f084be1fcbe33ad7480913e44d6130c421c0976f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`f2ab060`](https://github.com/mastra-ai/mastra/commit/f2ab060162bea81505fda553e2cee29c1979fd04), [`5d302c8`](https://github.com/mastra-ai/mastra/commit/5d302c8eda1a6ac74eab5e442c4f64db6cc97a06), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`a952852`](https://github.com/mastra-ai/mastra/commit/a952852c971a21fb646cd907c75fcf4443cdc963), [`2656d9c`](https://github.com/mastra-ai/mastra/commit/2656d9c2976d4f3354253bfbbbf9b88a1b2bbf34), [`63e3fe1`](https://github.com/mastra-ai/mastra/commit/63e3fe13cc1ea96f91d7c68aea92f400faf9e4da), [`1d4ce8d`](https://github.com/mastra-ai/mastra/commit/1d4ce8daaa54511f325c1b609d31b8e54009d677), [`8c68372`](https://github.com/mastra-ai/mastra/commit/8c68372e85fe0b066ec12c58bd29ffb93e54c552)]:
+  - @mastra/core@1.42.0
+
 ## 1.24.0-alpha.4
 
 ### 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.24.0-alpha.4"
+  version: "1.25.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.24.0-alpha.4",
+  "version": "1.25.0",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

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

@@ -522,6 +522,26 @@ response.processDataStream({
 })
 ```
 
+### Shape client tool output for the model
+
+Client tools support `toModelOutput` to control what the model receives, including multimodal content such as images. Because client tools execute locally, the mapping also runs on the client after `execute` completes. The transformed output is sent back to the server alongside the raw result, so the raw result stays available for storage and application logic.
+
+```typescript
+const screenshotTool = createTool({
+  id: 'takeScreenshot',
+  description: 'Takes a screenshot of the current page',
+  inputSchema: z.object({}),
+  execute: async () => {
+    const base64 = await captureScreenshot()
+    return { ok: true, data: base64 }
+  },
+  toModelOutput: output => ({
+    type: 'content',
+    value: [{ type: 'media', data: output.data, mediaType: 'image/jpeg' }],
+  }),
+})
+```
+
 ### Tracing client tools
 
 When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call, injects a W3C trace carrier into the outgoing tool-call chunk, and ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.

package/dist/index.cjs

@@ -302,6 +302,40 @@ function requestContextQueryString(requestContext, delimiter = "?") {
   const queryString = searchParams.toString();
   return queryString ? `${delimiter}${queryString}` : "";
 }
+
+// src/utils/client-tool-model-output.ts
+function normalizeModelOutput(output) {
+  if (output == null || typeof output !== "object") return output;
+  const obj = output;
+  if (obj.type !== "content" || !Array.isArray(obj.value)) return output;
+  return {
+    ...obj,
+    value: obj.value.map((item) => {
+      if (item == null || typeof item !== "object") return item;
+      const part = item;
+      if (part.type === "image-url" && typeof part.url === "string") {
+        const semicolonIndex = part.url.indexOf(";");
+        const commaIndex = part.url.indexOf(",");
+        const mediaTypeEnd = semicolonIndex === -1 ? commaIndex : commaIndex === -1 ? semicolonIndex : Math.min(semicolonIndex, commaIndex);
+        const mediaType = typeof part.mediaType === "string" && part.mediaType ? part.mediaType : part.url.startsWith("data:") ? part.url.slice(5, mediaTypeEnd === -1 ? void 0 : mediaTypeEnd) || "image/jpeg" : "image/jpeg";
+        return { type: "media", data: part.url, mediaType };
+      }
+      if (part.type === "image-data" && typeof part.data === "string") {
+        return { type: "media", data: part.data, mediaType: part.mediaType ?? "image/jpeg" };
+      }
+      if (part.type === "file-data" && typeof part.data === "string") {
+        return { type: "media", data: part.data, mediaType: part.mediaType ?? "application/octet-stream" };
+      }
+      return part;
+    })
+  };
+}
+async function getClientToolModelOutput(clientTool, result) {
+  const toModelOutput = clientTool.toModelOutput;
+  if (typeof toModelOutput !== "function" || result == null) return void 0;
+  const modelOutput = await toModelOutput(result);
+  return modelOutput == null ? void 0 : normalizeModelOutput(modelOutput);
+}
 function isZodType(value) {
   return typeof value === "object" && value !== null && "_def" in value && "parse" in value && typeof value.parse === "function" && "safeParse" in value && typeof value.safeParse === "function";
 }
@@ -596,11 +630,15 @@ async function executeToolCallAndRespond({
             }
           }
         });
+        const modelOutput = await getClientToolModelOutput(clientTool, result);
         const toolResultContent = {
           type: "tool-result",
           toolCallId: toolCall.payload.toolCallId,
           toolName: toolCall.payload.toolName,
-          result
+          result,
+          // Carry the client-side toModelOutput result so the server uses it
+          // when building the model prompt, while result keeps the raw value.
+          ...modelOutput != null ? { providerOptions: { mastra: { modelOutput } } } : {}
         };
         if (observability) {
           toolResultContent.__mastraObservability = observability;
@@ -948,6 +986,7 @@ var Agent = class extends BaseResource {
             const clientTool = activeClientTools[toolCall.toolName];
             if (!clientTool || typeof clientTool.execute !== "function") continue;
             let result;
+            let modelOutput;
             let observability;
             try {
               const execution = await executeClientToolWithObservability({
@@ -971,8 +1010,14 @@ var Agent = class extends BaseResource {
               });
               result = execution.result;
               observability = execution.observability;
+              try {
+                modelOutput = await getClientToolModelOutput(clientTool, result);
+              } catch {
+                modelOutput = void 0;
+              }
             } catch (error) {
               result = { error: String(error) };
+              modelOutput = void 0;
             }
             const toolResultContent = {
               type: "tool-result",
@@ -998,6 +1043,9 @@ var Agent = class extends BaseResource {
               toolCallId: toolCall.toolCallId,
               toolName: toolCall.toolName,
               output: { type: "json", value: result },
+              // Carry the client-side toModelOutput result so the server uses it
+              // when building the model prompt, while output keeps the raw result.
+              ...modelOutput != null ? { providerOptions: { mastra: { modelOutput } } } : {},
               ...observability ? { __mastraObservability: observability } : {}
             };
             toolResultMessages.push({
@@ -1979,6 +2027,7 @@ var Agent = class extends BaseResource {
                 shouldExecuteClientTool = true;
                 const runId = streamRunId ?? toolCall2.toolCallId;
                 let result;
+                let modelOutput;
                 let observability;
                 let synthetic;
                 try {
@@ -2001,6 +2050,7 @@ var Agent = class extends BaseResource {
                       }
                     }
                   }));
+                  modelOutput = await getClientToolModelOutput(clientTool, result);
                   synthetic = {
                     type: "tool-result",
                     runId,
@@ -2059,6 +2109,14 @@ var Agent = class extends BaseResource {
                     result,
                     ...observability ? { __mastraObservability: observability } : {}
                   };
+                  if (modelOutput != null) {
+                    const partWithMetadata = toolInvocationPart;
+                    const existingMastra = partWithMetadata.providerMetadata?.mastra != null && typeof partWithMetadata.providerMetadata.mastra === "object" ? partWithMetadata.providerMetadata.mastra : {};
+                    partWithMetadata.providerMetadata = {
+                      ...partWithMetadata.providerMetadata,
+                      mastra: { ...existingMastra, modelOutput }
+                    };
+                  }
                 }
                 const toolInvocation = lastMessage?.toolInvocations?.find(
                   (toolInvocation2) => toolInvocation2.toolCallId === toolCall2.toolCallId
@@ -4814,6 +4872,15 @@ var StoredAgent = class extends BaseResource {
       body: params
     });
   }
+  /**
+   * Opens a source-provider change request for deterministic agent JSON without mutating storage.
+   */
+  openChangeRequest(params) {
+    return this.request(`/stored/agents/${encodeURIComponent(this.storedAgentId)}/change-request`, {
+      method: "POST",
+      body: params
+    });
+  }
   /**
    * Deletes the stored agent
    * @param requestContext - Optional request context to pass as query parameter