@mastra/client-js 1.18.0-alpha.12 → 1.18.0-alpha.14

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @mastra/client-js
 
+## 1.18.0-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`f984b4d`](https://github.com/mastra-ai/mastra/commit/f984b4d6c60bf2ae2a9b156f0e8c35a66fe96c91), [`ce01024`](https://github.com/mastra-ai/mastra/commit/ce010242eee9bdfc09e4c26725b9d37998679a8d), [`f984b4d`](https://github.com/mastra-ai/mastra/commit/f984b4d6c60bf2ae2a9b156f0e8c35a66fe96c91), [`8373ff4`](https://github.com/mastra-ai/mastra/commit/8373ff46745d77af79f183c4470f80fa2727a6b2), [`11c1528`](https://github.com/mastra-ai/mastra/commit/11c152848c5d0ef227184853b5040f5b41ee7b1e)]:
+  - @mastra/core@1.33.0-alpha.13
+
+## 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

package/dist/_types/@internal_ai-sdk-v5/dist/index.d.ts

@@ -1547,16 +1547,16 @@ declare interface EventSourceMessage {
      * implementation in that browsers will default this to `message`, whereas this parser will
      * leave this as `undefined` if not explicitly declared.
      */
-    event?: string | undefined;
+    event?: string | undefined
     /**
      * ID of the message, if any was provided by the server. Can be used by clients to keep the
      * last received message ID in sync when reconnecting.
      */
-    id?: string | undefined;
+    id?: string | undefined
     /**
      * The data received for this message
      */
-    data: string;
+    data: string
 }
 
 /**
@@ -1580,11 +1580,8 @@ declare interface EventSourceMessage {
  *
  * @public
  */
-declare class EventSourceParserStream extends TransformStream<
-string,
-EventSourceMessage
-> {
-    constructor({ onError, onRetry, onComment }?: StreamOptions);
+declare class EventSourceParserStream extends TransformStream<string, EventSourceMessage> {
+    constructor({onError, onRetry, onComment}?: StreamOptions)
 }
 
 /**
@@ -6988,19 +6985,19 @@ declare interface StreamOptions {
      *
      * @defaultValue `undefined`
      */
-    onError?: ("terminate" | ((error: Error) => void)) | undefined;
+    onError?: ('terminate' | ((error: Error) => void)) | undefined
     /**
      * Callback for when a reconnection interval is sent from the server.
      *
      * @param retry - The number of milliseconds to wait before reconnecting.
      */
-    onRetry?: ((retry: number) => void) | undefined;
+    onRetry?: ((retry: number) => void) | undefined
     /**
      * Callback for when a comment is encountered in the stream.
      *
      * @param comment - The comment encountered in the stream.
      */
-    onComment?: ((comment: string) => void) | undefined;
+    onComment?: ((comment: string) => void) | undefined
 }
 
 /**

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.12"
+  version: "1.18.0-alpha.14"
 ---
 
 ## 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.12",
+  "version": "1.18.0-alpha.14",
   "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
   });
 }
 
@@ -348,8 +357,6 @@ var AgentVoice = class extends BaseResource {
     this.version = version;
     this.agentId = agentId;
   }
-  agentId;
-  version;
   getQueryString(requestContext, delimiter = "?") {
     const searchParams = new URLSearchParams(requestContextQueryString(requestContext).slice(1));
     if (this.version) {
@@ -419,8 +426,6 @@ var Agent = class extends BaseResource {
     this.version = version;
     this.voice = new AgentVoice(options, this.agentId, this.version);
   }
-  agentId;
-  version;
   voice;
   getQueryString(requestContext, delimiter = "?") {
     const searchParams = new URLSearchParams(requestContextQueryString(requestContext).slice(1));
@@ -446,6 +451,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
@@ -1905,8 +1942,6 @@ var MemoryThread = class extends BaseResource {
     this.threadId = threadId;
     this.agentId = agentId;
   }
-  threadId;
-  agentId;
   /**
    * Builds the query string for agentId (if provided)
    */
@@ -2039,7 +2074,6 @@ var Vector = class extends BaseResource {
     super(options);
     this.vectorName = vectorName;
   }
-  vectorName;
   /**
    * Retrieves details about a specific vector index
    * @param indexName - Name of the index to get details for
@@ -2112,7 +2146,6 @@ var Tool = class extends BaseResource {
     super(options);
     this.toolId = toolId;
   }
-  toolId;
   /**
    * Retrieves details about the tool
    * @param requestContext - Optional request context to pass as query parameter
@@ -2148,7 +2181,6 @@ var Processor = class extends BaseResource {
     super(options);
     this.processorId = processorId;
   }
-  processorId;
   /**
    * Retrieves details about the processor
    * @param requestContext - Optional request context to pass as query parameter
@@ -2230,8 +2262,6 @@ var Run = class extends BaseResource {
     this.workflowId = workflowId;
     this.runId = runId;
   }
-  workflowId;
-  runId;
   /**
    * Creates a transform stream that parses RECORD_SEPARATOR-delimited JSON chunks
    */
@@ -2624,7 +2654,6 @@ var Workflow = class extends BaseResource {
     super(options);
     this.workflowId = workflowId;
   }
-  workflowId;
   /**
    * Retrieves details about the workflow
    * @param requestContext - Optional request context to pass as query parameter
@@ -2987,7 +3016,6 @@ var A2A = class extends BaseResource {
     super(options);
     this.agentId = agentId;
   }
-  agentId;
   /**
    * Get the agent card with metadata about the agent.
    * @param options - Optional Agent Card verification settings
@@ -3236,7 +3264,6 @@ var AgentBuilder = class extends BaseResource {
     super(options);
     this.actionId = actionId;
   }
-  actionId;
   // Helper function to transform workflow result to action result
   transformWorkflowResult(result) {
     if (result.status === "success") {
@@ -3423,13 +3450,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 },
@@ -3963,7 +3991,6 @@ var StoredAgent = class extends BaseResource {
     super(options);
     this.storedAgentId = storedAgentId;
   }
-  storedAgentId;
   /**
    * Retrieves details about the stored agent
    * @param requestContext - Optional request context to pass as query parameter
@@ -4123,7 +4150,6 @@ var StoredPromptBlock = class extends BaseResource {
     super(options);
     this.storedPromptBlockId = storedPromptBlockId;
   }
-  storedPromptBlockId;
   /**
    * Retrieves details about the stored prompt block
    * @param requestContext - Optional request context to pass as query parameter
@@ -4283,7 +4309,6 @@ var StoredMCPClient = class extends BaseResource {
     super(options);
     this.storedMCPClientId = storedMCPClientId;
   }
-  storedMCPClientId;
   /**
    * Retrieves details about the stored MCP client
    * @param requestContext - Optional request context to pass as query parameter
@@ -4330,7 +4355,6 @@ var StoredScorer = class extends BaseResource {
     super(options);
     this.storedScorerId = storedScorerId;
   }
-  storedScorerId;
   /**
    * Retrieves details about the stored scorer definition
    * @param requestContext - Optional request context to pass as query parameter
@@ -4491,7 +4515,6 @@ var ToolProvider = class extends BaseResource {
     super(options);
     this.providerId = providerId;
   }
-  providerId;
   /**
    * Lists available toolkits from this provider
    * @returns Promise containing list of toolkits
@@ -4541,7 +4564,6 @@ var ProcessorProvider = class extends BaseResource {
     super(options);
     this.providerId = providerId;
   }
-  providerId;
   /**
    * Gets details about this processor provider and its available processors
    * @returns Promise containing provider info and processor list
@@ -4561,9 +4583,6 @@ var WorkspaceSkillResource = class extends BaseResource {
     this.basePath = `/workspaces/${encodeURIComponent(this.workspaceId)}/skills/${encodeURIComponent(this.skillName)}`;
     this.pathQuery = this.skillPath ? `?path=${encodeURIComponent(this.skillPath)}` : "";
   }
-  workspaceId;
-  skillName;
-  skillPath;
   basePath;
   pathQuery;
   /**
@@ -4783,7 +4802,6 @@ var StoredSkill = class extends BaseResource {
     super(options);
     this.storedSkillId = storedSkillId;
   }
-  storedSkillId;
   /**
    * Retrieves details about the stored skill
    * @param requestContext - Optional request context to pass as query parameter
@@ -4880,7 +4898,6 @@ var ResponsesStream = class {
   constructor(response) {
     this.response = response;
   }
-  response;
   asResponse() {
     return this.response;
   }
@@ -5290,7 +5307,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