@mastra/client-js 1.18.0-alpha.11 → 1.18.0-alpha.13

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @mastra/client-js
 
+## 1.18.0-alpha.13
+
+### Minor Changes
+
+- Added Agent signals for sending contextual messages into agent thread loops and subscribing to thread activity. ([#16229](https://github.com/mastra-ai/mastra/pull/16229))
+
+  Call `agent.sendSignal()` to inject context into a running agent loop. When the thread is idle, that same signal becomes the prompt that starts the next loop by default. Use `ifActive.behavior` and `ifIdle.behavior` to deliver, persist, discard, or wake from a signal.
+
+  Use `agent.subscribeToThread()` to follow the raw stream chunks for a memory thread, observe signal echoes with stable IDs, and abort the active stream for that thread.
+
+  ```ts
+  const subscription = await agent.subscribeToThread({ resourceId, threadId });
+
+  void (async () => {
+    for await (const part of subscription.stream) {
+      if (part.type === 'finish') {
+        subscription.unsubscribe();
+      }
+    }
+  })();
+
+  agent.sendSignal({ type: 'user-message', contents: 'Use the latest answer' }, { resourceId, threadId });
+  ```
+
+- Fix client-js bugs surfaced by the SDK ↔ server contract audit. ([#16439](https://github.com/mastra-ai/mastra/pull/16439))
+  - `MastraClient.getAgentBuilderActions()` previously requested `/agent-builder/` (trailing slash) and 404'd. Now hits `/agent-builder`.
+  - `AgentBuilder.stream(params, runId)` now requires `runId`. The server route requires it; calls without it failed with a server-side validation error. The SDK now both types `runId` as required and guards at runtime.
+  - `MastraClient.createStoredSkill(...)` now requires `description` in its parameter type. The server schema has always required it; the SDK type used to mark it optional, so omitting it produced a runtime 400 instead of a compile error.
+
+  Migration:
+
+  ```ts
+  // Before
+  await agentBuilder.stream({ inputData });
+
+  // After
+  await agentBuilder.stream({ inputData }, runId);
+  ```
+
+  ```ts
+  // Before
+  await client.createStoredSkill({ name, instructions });
+
+  // After
+  await client.createStoredSkill({ name, description, instructions });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`b59316f`](https://github.com/mastra-ai/mastra/commit/b59316ffa0f7688165b0f9c81ccdf85da461e5b2), [`55f1e2d`](https://github.com/mastra-ai/mastra/commit/55f1e2d65425b95a49ae788053b266f256e38c96), [`d48a705`](https://github.com/mastra-ai/mastra/commit/d48a705ff3dfbdc7a996e07ecd8293b5effd9a2a)]:
+  - @mastra/core@1.33.0-alpha.12
+
+## 1.18.0-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`37c0dc5`](https://github.com/mastra-ai/mastra/commit/37c0dc5697d343db98628bf867bf71ce6deec6d7), [`ef6b584`](https://github.com/mastra-ai/mastra/commit/ef6b5847ac33c0a7e80af3a86e8801e2933dd3ee), [`4dd900d`](https://github.com/mastra-ai/mastra/commit/4dd900d75dfe9be89f8c15188b368a8622aa1e18), [`4ff5bdf`](https://github.com/mastra-ai/mastra/commit/4ff5bdfe170cba6dfb5260c6af0f4ba668430772), [`bbcd93c`](https://github.com/mastra-ai/mastra/commit/bbcd93cf7d8aa1007d6d84bfd033b8015c912087), [`308bd07`](https://github.com/mastra-ai/mastra/commit/308bd074f35cef0c75d82fc1eb19382fe04ecf6f)]:
+  - @mastra/core@1.33.0-alpha.11
+
 ## 1.18.0-alpha.11
 
 ### 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.18.0-alpha.11"
+  version: "1.18.0-alpha.13"
 ---
 
 ## When to use
@@ -16,6 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
+- [Signals](references/docs-agents-signals.md) - Learn how to send real-time context into a Mastra agent thread.
 - [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.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.0-alpha.11",
+  "version": "1.18.0-alpha.13",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

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

@@ -0,0 +1,151 @@
+# Signals
+
+> **Experimental:** Agent signals are experimental. The API may change in a future release.
+
+Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
+
+Signals are a context engineering tool for guiding the agent in real time as the agent loop progresses. Use them to add system-generated content from external event sources, such as incoming email notifications, GitHub pull request comments, background task notifications, and similar events.
+
+## Quickstart
+
+Subscribe to the thread before sending signals. The subscription receives the active stream when the signal wakes the agent or enters a running loop.
+
+```typescript
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Compare that with the previous option.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+
+for await (const chunk of subscription.stream) {
+  console.log(chunk)
+}
+```
+
+When the thread has a running agent stream, the signal becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input.
+
+## Control signal behavior
+
+By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
+
+```typescript
+const result = agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Store this for later, but do not wake the agent.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+    ifIdle: {
+      behavior: 'persist',
+    },
+  },
+)
+
+await result.persisted
+```
+
+The behavior options are:
+
+- `ifActive.behavior: 'deliver'`: Add the signal to the running agent loop. This is the default.
+- `ifActive.behavior: 'persist'`: Save the signal to memory without adding it to the running loop.
+- `ifActive.behavior: 'discard'`: Ignore the signal while the thread is active.
+- `ifIdle.behavior: 'wake'`: Start a stream with the signal as the first input. This is the default.
+- `ifIdle.behavior: 'persist'`: Save the signal to memory without starting a stream.
+- `ifIdle.behavior: 'discard'`: Ignore the signal while the thread is idle.
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You do not need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Continue with the next step.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+    ifIdle: {
+      behavior: 'wake',
+      streamOptions: {
+        maxSteps: 3,
+      },
+    },
+  },
+)
+```
+
+## Send external event context
+
+Use custom signal types for system-generated context. Non-user signal types are rendered as XML-style user-role context so they can appear inside conversation history without looking like assistant output.
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'system-reminder',
+    contents: 'User X has left a new PR comment asking for a smaller API surface.',
+    attributes: {
+      type: 'github',
+      pr: '123',
+    },
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives the custom signal as context like this:
+
+```xml
+<system-reminder type="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+```
+
+Use XML-safe signal type names and attribute names. Signal type names and attribute names can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
+
+## Use the client SDK
+
+The JavaScript client exposes the same thread signal APIs. Use `subscribeToThread()` before `sendSignal()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = client.getAgent('supportAgent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Show the shorter version.',
+  },
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+await subscription.processDataStream({
+  onChunk: chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+## Related
+
+- [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
+- [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)

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

@@ -151,6 +151,95 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `sendSignal()`
+
+Send a signal to an active agent run or memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const result = await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Also consider the customer note I just added.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+console.log(result.runId)
+```
+
+Use `ifActive.behavior` and `ifIdle.behavior` to control whether Mastra delivers, persists, discards, or wakes from a signal:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Store this for later.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'persist',
+  },
+})
+```
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context:
+
+```typescript
+await agent.sendSignal({
+  signal: { type: 'user-message', contents: 'Start from this signal.' },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
+    },
+  },
+})
+```
+
+Returns `{ accepted: true, runId: string }`.
+
+**signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to contextual XML before the next model call.
+
+**runId** (`string`): Run ID to target directly.
+
+**resourceId** (`string`): Resource ID for the memory thread. Use with \`threadId\` for thread-targeted signals.
+
+**threadId** (`string`): Thread ID to target. Use with \`resourceId\` for thread-targeted signals.
+
+**ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
+
+**ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
+
+**ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`.
+
+### `subscribeToThread()`
+
+Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendSignal()`.
+
+```typescript
+const agent = mastraClient.getAgent('support-agent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+
+await subscription.processDataStream({
+  onChunk: async chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+`subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted.
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread ID to subscribe to.
+
 ### `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

@@ -135,11 +135,15 @@ function processClientTools(clientTools) {
 // src/utils/process-mastra-stream.ts
 async function sharedProcessMastraStream({
   stream,
-  onChunk
+  onChunk,
+  signal
 }) {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
+  const abort = () => void reader.cancel();
+  if (signal?.aborted) abort();
+  else signal?.addEventListener("abort", abort, { once: true });
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -167,25 +171,30 @@ async function sharedProcessMastraStream({
       }
     }
   } finally {
+    signal?.removeEventListener("abort", abort);
     reader.releaseLock();
   }
 }
 async function processMastraNetworkStream({
   stream,
-  onChunk
+  onChunk,
+  signal
 }) {
   return sharedProcessMastraStream({
     stream,
-    onChunk
+    onChunk,
+    signal
   });
 }
 async function processMastraStream({
   stream,
-  onChunk
+  onChunk,
+  signal
 }) {
   return sharedProcessMastraStream({
     stream,
-    onChunk
+    onChunk,
+    signal
   });
 }
 
@@ -446,6 +455,38 @@ var Agent = class extends BaseResource {
       body: { instructions, comment }
     });
   }
+  /**
+   * @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
+    });
+  }
+  /**
+   * @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`, {
+      method: "POST",
+      body: params,
+      stream: true
+    });
+    if (!streamResponse.body) {
+      throw new Error("No response body");
+    }
+    streamResponse.processDataStream = async ({
+      onChunk
+    }) => {
+      await processMastraStream({
+        stream: streamResponse.body,
+        onChunk,
+        signal: this.options.abortSignal
+      });
+    };
+    return streamResponse;
+  }
   /**
    * Clones this agent to a new stored agent in the database
    * @param params - Clone parameters including optional newId, newName, metadata, authorId, and requestContext
@@ -3423,13 +3464,14 @@ var AgentBuilder = class extends BaseResource {
    * This calls `/agent-builder/:actionId/stream`.
    */
   async stream(params, runId) {
-    const searchParams = new URLSearchParams();
-    if (runId) {
-      searchParams.set("runId", runId);
+    if (!runId) {
+      throw new Error("runId is required to stream an agent builder action");
     }
+    const searchParams = new URLSearchParams();
+    searchParams.set("runId", runId);
     const requestContext = parseClientRequestContext(params.requestContext);
     const { requestContext: _, ...actionParams } = params;
-    const url = `/agent-builder/${this.actionId}/stream${searchParams.toString() ? `?${searchParams.toString()}` : ""}`;
+    const url = `/agent-builder/${this.actionId}/stream?${searchParams.toString()}`;
     const response = await this.request(url, {
       method: "POST",
       body: { ...actionParams, requestContext },
@@ -5290,7 +5332,7 @@ var MastraClient = class extends BaseResource {
    * @returns Promise containing map of action IDs to action details
    */
   getAgentBuilderActions() {
-    return this.request("/agent-builder/");
+    return this.request("/agent-builder");
   }
   /**
    * Gets an agent builder instance for executing agent-builder workflows