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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mastra/client-js
 
+## 1.22.0-alpha.6
+
+### Patch Changes
+
+- Separated thread subscription cleanup from active-run aborts so closing or switching a listener only unsubscribes that listener, while explicit cancel still aborts the active run. ([#17310](https://github.com/mastra-ai/mastra/pull/17310))
+
+- Added subscription-native tool approval APIs so approving or declining a tool call resumes through the active thread subscription instead of requiring a separate continuation stream. New messages are queued while a tool approval is waiting, preventing overlapping runs from duplicating approval requests. ([#17311](https://github.com/mastra-ai/mastra/pull/17311))
+
+  ```ts
+  await agent.sendToolApproval({
+    resourceId: 'user-123',
+    threadId: 'thread-123',
+    toolCallId: 'tool-call-123',
+    approved: true,
+  });
+  ```
+
+- Updated dependencies [[`19a8658`](https://github.com/mastra-ai/mastra/commit/19a86589c788ef48bb6c1b0612cc82a201857379), [`a659a77`](https://github.com/mastra-ai/mastra/commit/a659a779bdebe3a52a518c56d2260592d0240fe0), [`3332be9`](https://github.com/mastra-ai/mastra/commit/3332be9701ecd77aba840959d9a1d1ce7aef02d3)]:
+  - @mastra/core@1.38.0-alpha.6
+
 ## 1.22.0-alpha.5
 
 ### 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.5"
+  version: "1.22.0-alpha.6"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -233,9 +233,24 @@ Existing stored signal rows and older clients continue to load through the compa
 
 > **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
+## Approve tool calls
+
+When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The call returns a JSON acknowledgement. The resumed chunks arrive through the existing thread subscription.
+
+```typescript
+await agent.sendToolApproval({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+  toolCallId: 'tool-call_456',
+  approved: true,
+})
+```
+
+Pass `approved: false` to decline the same pending tool call. Use the older `approveToolCall()` and `declineToolCall()` methods only when you are rendering the separate continuation stream directly.
+
 ## Use HTTP routes
 
-If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
+If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. For subscription-native tool approval, use `POST /api/agents/:agentId/send-tool-approval`. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
 
 ## Use the client SDK
 
@@ -294,4 +309,5 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
-- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)

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

@@ -326,7 +326,7 @@ response.processDataStream({
 
 ### `approveToolCall()`
 
-Approve a pending tool call that requires human confirmation:
+Approve a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the approval response.
 
 ```typescript
 const response = await agent.approveToolCall({
@@ -341,9 +341,26 @@ response.processDataStream({
 })
 ```
 
+### `sendToolApproval()`
+
+Approve or decline a pending tool call for a subscribed thread. Use this with `subscribeToThread()` when the resumed chunks should arrive through the existing thread subscription instead of a separate continuation stream.
+
+```typescript
+const result = await agent.sendToolApproval({
+  resourceId: 'user-123',
+  threadId: 'thread-456',
+  toolCallId: 'tool-call-456',
+  approved: true,
+})
+
+console.log(result.accepted)
+```
+
+Returns `{ accepted: true, runId: string, toolCallId?: string }`.
+
 ### `declineToolCall()`
 
-Decline a pending tool call that requires human confirmation:
+Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response.
 
 ```typescript
 const response = await agent.declineToolCall({

package/dist/index.cjs

@@ -862,173 +862,216 @@ var Agent = class extends BaseResource {
       throw new Error("No response body");
     }
     const agent = this;
+    streamResponse.abort = async () => (await agent.abortThread({ resourceId, threadId })).aborted;
+    let unsubscribed = false;
+    let processAbortController;
+    let processStarted = false;
+    streamResponse.unsubscribe = () => {
+      if (unsubscribed) return;
+      unsubscribed = true;
+      processAbortController?.abort();
+      if (!processStarted) {
+        void streamResponse.body?.cancel().catch(() => {
+        });
+      }
+    };
     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) };
+      if (unsubscribed) return;
+      processStarted = true;
+      processAbortController = new AbortController();
+      const abortProcessStream = () => processAbortController?.abort();
+      const isClosed = () => unsubscribed || processAbortController?.signal.aborted || this.options.abortSignal?.aborted;
+      if (this.options.abortSignal?.aborted) {
+        abortProcessStream();
+      } else {
+        this.options.abortSignal?.addEventListener("abort", abortProcessStream, { once: true });
+      }
+      try {
+        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;
           }
-          const toolResultContent = {
-            type: "tool-result",
-            toolCallId: toolCall.toolCallId,
-            toolName: toolCall.toolName,
-            result
-          };
-          if (observability) {
-            toolResultContent.__mastraObservability = observability;
+          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;
           }
-          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 {
+          const pendingToolCalls = pendingToolCallsByRunId.get(runId);
+          pendingToolCallsByRunId.delete(runId);
+          if (!pendingToolCalls?.length) {
+            agent.deleteSignalRuntimeOptions(runId);
+            return;
           }
-        } 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;
+          const activeRuntimeOptions = agent.getSignalRuntimeOptions({ runId, resourceId, threadId });
+          const activeClientTools = activeRuntimeOptions?.clientTools;
+          if (!activeClientTools) {
+            agent.deleteSignalRuntimeOptions(runId);
+            return;
           }
-          if (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
-            throw error;
+          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 (!reconnectOptions || this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
-          return;
-        }
-        while (attempts < reconnectOptions.maxRetries) {
-          attempts++;
-          if (this.options.abortSignal?.aborted) {
+          if (toolResultMessages.length === 0) {
+            agent.deleteSignalRuntimeOptions(runId);
             return;
           }
-          await new Promise((resolve) => setTimeout(resolve, reconnectOptions.delayMs));
-          if (this.options.abortSignal?.aborted) {
-            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 {
-            response = await requestSubscription();
-            break;
+            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: processAbortController.signal
+            });
           } catch (error) {
-            if (this.options.abortSignal?.aborted || attempts >= reconnectOptions.maxRetries) {
+            if (typeof error === "object" && error !== null && error[onChunkErrorSentinel]) {
+              throw error.cause;
+            }
+            if (!reconnectOptions || isClosed() || attempts >= reconnectOptions.maxRetries) {
+              if (isClosed()) return;
               throw error;
             }
           }
+          if (!reconnectOptions || isClosed() || attempts >= reconnectOptions.maxRetries) {
+            return;
+          }
+          while (attempts < reconnectOptions.maxRetries) {
+            attempts++;
+            if (isClosed()) {
+              return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, reconnectOptions.delayMs));
+            if (isClosed()) {
+              return;
+            }
+            try {
+              response = await requestSubscription();
+              break;
+            } catch (error) {
+              if (isClosed() || attempts >= reconnectOptions.maxRetries) {
+                if (isClosed()) return;
+                throw error;
+              }
+            }
+          }
+        }
+      } finally {
+        this.options.abortSignal?.removeEventListener("abort", abortProcessStream);
+        if (processAbortController?.signal.aborted) {
+          unsubscribed = true;
         }
+        processAbortController = void 0;
       }
     };
     return streamResponse;
   }
+  /**
+   * @experimental Agent signals are experimental and may change in a future release.
+   */
+  async abortThread(params) {
+    const { resourceId, threadId } = params;
+    return this.request(`/agents/${this.agentId}/threads/abort`, {
+      method: "POST",
+      body: { resourceId, threadId }
+    });
+  }
   /**
    * Clones this agent to a new stored agent in the database
    * @param params - Clone parameters including optional newId, newName, metadata, authorId, and requestContext
@@ -2220,6 +2263,16 @@ var Agent = class extends BaseResource {
     };
     return streamResponse;
   }
+  async sendToolApproval(params) {
+    const { requestContext, ...rest } = params;
+    return this.request(
+      `/agents/${this.agentId}/send-tool-approval`,
+      {
+        method: "POST",
+        body: { ...rest, requestContext: parseClientRequestContext(requestContext) }
+      }
+    );
+  }
   async declineToolCall(params) {
     const { requestContext, ...rest } = params;
     const processedParams = { ...rest, requestContext: parseClientRequestContext(requestContext) };