@mastra/client-js 1.21.0-alpha.7 → 1.21.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @mastra/client-js
 
+## 1.21.0-alpha.8
+
+### Patch Changes
+
+- Made optional memory response fields optional in server schemas and generated client types. ([#17070](https://github.com/mastra-ai/mastra/pull/17070))
+
+- Add `StoredSkill.favorite()` and `StoredSkill.unfavorite()` methods, mirroring the existing `StoredAgent` favorite API. Both are idempotent and call `PUT`/`DELETE /api/stored/skills/:id/favorite`. ([#17101](https://github.com/mastra-ai/mastra/pull/17101))
+
+- Agent Builder action routes (`/agent-builder/*`) are now registered automatically through the standard server route pipeline. Any adapter built on `@mastra/server` (Hono, Express, Fastify, Koa, etc.) serves the 15 `/agent-builder/*` endpoints without consumers wiring them manually. ([#17085](https://github.com/mastra-ai/mastra/pull/17085))
+
+  **Example**
+
+  ```ts
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:4111' });
+
+  // `/agent-builder/*` routes are now reachable out-of-the-box
+  const actions = await client.getAgentBuilderActions();
+
+  const action = client.getAgentBuilderAction('generate-agent');
+  const { runId } = await action.createRun();
+  const result = await action.startAsync({ inputData: { prompt: 'Build me an agent' } }, runId);
+  ```
+
+  **Why**
+
+  Previously, `AGENT_BUILDER_ROUTES` was a type-only entry in the route registry to keep `@mastra/agent-builder` out of Cloudflare worker bundles. Consumers had to register the routes themselves to expose Agent Builder functionality. Lazy-loading of `@mastra/agent-builder` is preserved — handlers still resolve the workflow module on first request via dynamic `import()`, so Cloudflare bundles are unaffected.
+
+  **New EE permissions**
+
+  The following permissions are added to the EE registry. RBAC consumers with strict allowlists must grant these to retain access to builder action routes:
+  - `agent-builder:read`
+  - `agent-builder:write`
+  - `agent-builder:execute`
+
+  Two legacy stream routes (`STREAM_LEGACY_AGENT_BUILDER_ACTION_ROUTE`, `OBSERVE_STREAM_LEGACY_AGENT_BUILDER_ACTION_ROUTE`) are now registered through the standard pipeline as well.
+
+- Improved agent thread subscription resilience by keeping server streams active during idle periods and allowing the JavaScript client to reconnect when subscription streams close or resubscribe requests fail. ([#17045](https://github.com/mastra-ai/mastra/pull/17045))
+
+  Enable automatic reconnection with `subscription.processDataStream({ onChunk: chunk => console.log(chunk), reconnect: true })`.
+
+- Fixed `clientTools` being silently dropped — and never executed — on thread-backed chats. When a chat had a `threadId`, the React `useChat` hook routed messages through the new agent signals path but did not pass the `clientTools` map into the signal startup flow, so client-side tools were unavailable when the model requested them. ([#16540](https://github.com/mastra-ai/mastra/pull/16540))
+
+  The signals path now carries `clientTools` and other per-send stream options on `sendSignal`. When the subscribed stream finishes with `tool-calls`, the client executes matching local tools with observability support, emits tool result chunks, and posts a continuation with the assistant tool-call messages plus tool-result messages so the run resumes on the same thread with the same per-send options.
+
+- Updated dependencies [[`c35b962`](https://github.com/mastra-ai/mastra/commit/c35b9625c7e854fcfdeee226a3338a750d0ff211), [`4084113`](https://github.com/mastra-ai/mastra/commit/408411370fc48a822e8b616b3b63f9409774e0e9)]:
+  - @mastra/core@1.37.0-alpha.8
+
 ## 1.21.0-alpha.7
 
 ### 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.0-alpha.7"
+  version: "1.21.0-alpha.8"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0-alpha.7",
+  "version": "1.21.0-alpha.8",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

package/dist/docs/references/docs-agents-signals.md

@@ -204,9 +204,30 @@ await subscription.processDataStream({
   onChunk: chunk => {
     console.log(chunk)
   },
+  reconnect: true,
 })
 ```
 
+Use `reconnect: true` for long-lived subscriptions. The client resubscribes when the stream closes or a reconnect request fails, such as after a proxy idle timeout or a dropped network connection.
+
+## Keep custom SSE subscriptions alive
+
+If you expose your own Server-Sent Events (SSE) endpoint for thread subscriptions, send periodic heartbeat frames while the stream is idle. This keeps browsers, proxies, and load balancers from closing the connection before the next signal or model chunk arrives.
+
+The following example sends an SSE comment every 25 seconds:
+
+```typescript
+const heartbeat = setInterval(() => {
+  controller.enqueue(encoder.encode(': keep-alive\n\n'))
+}, 25_000)
+
+request.signal.addEventListener('abort', () => {
+  clearInterval(heartbeat)
+})
+```
+
+Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle disconnects, while reconnects recover when the network or runtime still closes the stream.
+
 ## Related
 
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)

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

@@ -228,18 +228,21 @@ const subscription = await agent.subscribeToThread({
 })
 
 await subscription.processDataStream({
-  onChunk: async chunk => {
+  onChunk: chunk => {
     console.log(chunk)
   },
+  reconnect: true,
 })
 ```
 
-`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted. Pass `reconnect: true` to resubscribe when the transport closes or a reconnect request fails, such as after a proxy idle timeout.
 
 **resourceId** (`string`): Resource ID for the memory thread.
 
 **threadId** (`string`): Thread ID to subscribe to.
 
+**processDataStream().reconnect** (`boolean | { maxRetries?: number; delayMs?: number }`): Reconnects the subscription stream after it closes or a reconnect request fails. \`true\` retries indefinitely with a one-second delay.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.

package/dist/index.cjs

@@ -499,6 +499,24 @@ var BaseResource = class {
 };
 
 // src/resources/agent.ts
+var SIGNAL_RUNTIME_OPTIONS_TTL_MS = 5 * 60 * 1e3;
+var signalRuntimeOptionsByRunId = /* @__PURE__ */ new Map();
+var latestSignalRuntimeOptionsByThread = /* @__PURE__ */ new Map();
+var createSignalRuntimeOptionsEntry = (store, key, streamOptions) => {
+  const timeout = setTimeout(() => store.delete(key), SIGNAL_RUNTIME_OPTIONS_TTL_MS);
+  timeout.unref?.();
+  return { streamOptions, timeout };
+};
+var setSignalRuntimeOptionsEntry = (store, key, streamOptions) => {
+  const existing = store.get(key);
+  if (existing) clearTimeout(existing.timeout);
+  store.set(key, createSignalRuntimeOptionsEntry(store, key, streamOptions));
+};
+var deleteSignalRuntimeOptionsEntry = (store, key) => {
+  const existing = store.get(key);
+  if (existing) clearTimeout(existing.timeout);
+  store.delete(key);
+};
 var noopClientToolObserve = {
   async span(_name, fn) {
     return fn();
@@ -696,6 +714,52 @@ var Agent = class extends BaseResource {
     const queryString = searchParams.toString();
     return queryString ? `${delimiter}${queryString}` : "";
   }
+  getSignalRuntimeRunKey(runId) {
+    return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${runId}`;
+  }
+  getSignalRuntimeThreadKey({
+    resourceId,
+    threadId
+  }) {
+    if (!threadId) return void 0;
+    return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${resourceId ?? ""}|${threadId}`;
+  }
+  setSignalRuntimeOptions({
+    runId,
+    resourceId,
+    threadId,
+    streamOptions
+  }) {
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    if (runId) {
+      setSignalRuntimeOptionsEntry(signalRuntimeOptionsByRunId, this.getSignalRuntimeRunKey(runId), streamOptions);
+      if (threadKey) deleteSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey);
+      return;
+    }
+    if (threadKey) {
+      setSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey, streamOptions);
+    }
+  }
+  getSignalRuntimeOptions({
+    runId,
+    resourceId,
+    threadId
+  }) {
+    if (runId) {
+      const runOptions = signalRuntimeOptionsByRunId.get(this.getSignalRuntimeRunKey(runId));
+      if (runOptions) return runOptions.streamOptions;
+    }
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    return threadKey ? latestSignalRuntimeOptionsByThread.get(threadKey)?.streamOptions : void 0;
+  }
+  deleteSignalRuntimeOptions(runId) {
+    if (!runId) return;
+    deleteSignalRuntimeOptionsEntry(signalRuntimeOptionsByRunId, this.getSignalRuntimeRunKey(runId));
+  }
+  deleteLatestSignalRuntimeOptions({ resourceId, threadId }) {
+    const threadKey = this.getSignalRuntimeThreadKey({ resourceId, threadId });
+    if (threadKey) deleteSignalRuntimeOptionsEntry(latestSignalRuntimeOptionsByThread, threadKey);
+  }
   /**
    * Retrieves details about the agent
    * @param requestContext - Optional request context to pass as query parameter
@@ -741,32 +805,227 @@ var Agent = class extends BaseResource {
   /**
    * @experimental Agent signals are experimental and may change in a future release.
    */
-  sendSignal(params) {
-    return this.request(`/agents/${this.agentId}/signals`, {
-      method: "POST",
-      body: params
-    });
+  async sendSignal(params) {
+    const streamOptions = params.ifIdle?.streamOptions;
+    if (streamOptions) {
+      this.setSignalRuntimeOptions({
+        resourceId: params.resourceId,
+        threadId: params.threadId,
+        streamOptions
+      });
+    }
+    const body = params.ifIdle?.streamOptions ? {
+      ...params,
+      ifIdle: {
+        ...params.ifIdle,
+        streamOptions: {
+          ...params.ifIdle.streamOptions,
+          requestContext: parseClientRequestContext(params.ifIdle.streamOptions.requestContext),
+          clientTools: processClientTools(params.ifIdle.streamOptions.clientTools)
+        }
+      }
+    } : params;
+    let response;
+    try {
+      response = await this.request(`/agents/${this.agentId}/signals`, {
+        method: "POST",
+        body
+      });
+    } catch (error) {
+      if (streamOptions) {
+        this.deleteLatestSignalRuntimeOptions({ resourceId: params.resourceId, threadId: params.threadId });
+      }
+      throw error;
+    }
+    if (streamOptions) {
+      this.setSignalRuntimeOptions({
+        runId: response.runId,
+        resourceId: params.resourceId,
+        threadId: params.threadId,
+        streamOptions
+      });
+    }
+    return response;
   }
   /**
    * @experimental Agent signals are experimental and may change in a future release.
    */
   async subscribeToThread(params) {
-    const streamResponse = await this.request(`/agents/${this.agentId}/threads/subscribe`, {
+    const { resourceId, threadId } = params;
+    const requestSubscription = () => this.request(`/agents/${this.agentId}/threads/subscribe`, {
       method: "POST",
-      body: params,
+      body: { resourceId, threadId },
       stream: true
     });
+    const streamResponse = await requestSubscription();
     if (!streamResponse.body) {
       throw new Error("No response body");
     }
-    streamResponse.processDataStream = async ({
-      onChunk
-    }) => {
-      await processMastraStream({
-        stream: streamResponse.body,
-        onChunk,
-        signal: this.options.abortSignal
-      });
+    const agent = this;
+    streamResponse.processDataStream = async ({ onChunk, reconnect }) => {
+      const pendingToolCallsByRunId = /* @__PURE__ */ new Map();
+      const handleSubscribedChunk = async (chunk) => {
+        if (chunk.type === "tool-call") {
+          const payload = chunk.payload;
+          const toolCallId = payload?.toolCallId;
+          const toolName = payload?.toolName;
+          const runId2 = chunk.runId;
+          if (!toolCallId || !toolName || !runId2) return;
+          const pendingToolCalls2 = pendingToolCallsByRunId.get(runId2) ?? [];
+          pendingToolCalls2.push({ toolCallId, toolName, args: payload.args, observability: payload.observability });
+          pendingToolCallsByRunId.set(runId2, pendingToolCalls2);
+          return;
+        }
+        if (chunk.type !== "finish") return;
+        const runId = chunk.runId;
+        const finishPayload = chunk;
+        if (!runId) return;
+        if (finishPayload.payload?.stepResult?.reason !== "tool-calls") {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const pendingToolCalls = pendingToolCallsByRunId.get(runId);
+        pendingToolCallsByRunId.delete(runId);
+        if (!pendingToolCalls?.length) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const activeRuntimeOptions = agent.getSignalRuntimeOptions({ runId, resourceId, threadId });
+        const activeClientTools = activeRuntimeOptions?.clientTools;
+        if (!activeClientTools) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        const activeRequestContext = activeRuntimeOptions.requestContext;
+        const processedClientTools = processClientTools(activeClientTools);
+        const processedRequestContext = parseClientRequestContext(activeRequestContext);
+        const toolResultMessages = [];
+        for (const toolCall of pendingToolCalls) {
+          const clientTool = activeClientTools[toolCall.toolName];
+          if (!clientTool || typeof clientTool.execute !== "function") continue;
+          let result;
+          let observability;
+          try {
+            const execution = await executeClientToolWithObservability({
+              clientTool,
+              args: toolCall.args,
+              toolName: toolCall.toolName,
+              parentContext: toolCall.observability,
+              executeContext: {
+                requestContext: activeRequestContext,
+                tracingContext: { currentSpan: void 0 },
+                agent: {
+                  agentId: agent.agentId,
+                  messages: finishPayload.payload?.messages?.nonUser ?? [],
+                  toolCallId: toolCall.toolCallId,
+                  suspend: async () => {
+                  },
+                  threadId,
+                  resourceId
+                }
+              }
+            });
+            result = execution.result;
+            observability = execution.observability;
+          } catch (error) {
+            result = { error: String(error) };
+          }
+          const toolResultContent = {
+            type: "tool-result",
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            result
+          };
+          if (observability) {
+            toolResultContent.__mastraObservability = observability;
+          }
+          await onChunk({
+            type: "tool-result",
+            runId,
+            payload: toolResultContent
+          });
+          toolResultMessages.push({
+            role: "tool",
+            content: [toolResultContent]
+          });
+        }
+        if (toolResultMessages.length === 0) {
+          agent.deleteSignalRuntimeOptions(runId);
+          return;
+        }
+        try {
+          const continuation = await agent.streamUntilIdle(
+            [...finishPayload.payload?.messages?.nonUser ?? [], ...toolResultMessages],
+            {
+              ...activeRuntimeOptions,
+              runId: uuid.v4(),
+              requestContext: processedRequestContext,
+              memory: threadId ? { thread: threadId, resource: resourceId } : void 0,
+              clientTools: processedClientTools
+            }
+          );
+          try {
+            void continuation.body?.cancel?.();
+          } catch {
+          }
+        } catch (error) {
+          console.error("Error running client-tool continuation:", error);
+        } finally {
+          agent.deleteSignalRuntimeOptions(runId);
+        }
+      };
+      const reconnectOptions = reconnect === true ? { maxRetries: Infinity, delayMs: 1e3 } : reconnect ? { maxRetries: reconnect.maxRetries ?? Infinity, delayMs: reconnect.delayMs ?? 1e3 } : null;
+      let response = streamResponse;
+      let attempts = 0;
+      const onChunkErrorSentinel = /* @__PURE__ */ Symbol("onChunkErrorSentinel");
+      const guardedOnChunk = async (chunk) => {
+        try {
+          await onChunk(chunk);
+          await handleSubscribedChunk(chunk);
+        } catch (cause) {
+          throw { [onChunkErrorSentinel]: true, cause };
+        }
+      };
+      while (true) {
+        if (!response.body) {
+          throw new Error("No response body");
+        }
+        try {
+          await processMastraStream({
+            stream: response.body,
+            onChunk: guardedOnChunk,
+            signal: this.options.abortSignal
+          });
+        } catch (error) {
+          if (typeof error === "object" && error !== null && error[onChunkErrorSentinel]) {
+            throw error.cause;
+          }
+          if (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+            throw error;
+          }
+        }
+        if (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+          return;
+        }
+        while (attempts < reconnectOptions.maxRetries) {
+          attempts++;
+          if (this.options.abortSignal?.aborted) {
+            return;
+          }
+          await new Promise((resolve) => setTimeout(resolve, reconnectOptions.delayMs));
+          if (this.options.abortSignal?.aborted) {
+            return;
+          }
+          try {
+            response = await requestSubscription();
+            break;
+          } catch (error) {
+            if (this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+              throw error;
+            }
+          }
+        }
+      }
     };
     return streamResponse;
   }