@mastra/client-js 1.21.2-alpha.2 → 1.22.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/client-js
 
+## 1.22.0-alpha.3
+
+### Minor Changes
+
+- Add fire-and-forget workflow resume that returns immediately with `{ runId }` without awaiting the run output. ([#17230](https://github.com/mastra-ai/mastra/pull/17230))
+
+  For `@mastra/inngest`, this skips the `getRunOutput()` polling that previously raced a realtime subscription against the Inngest runs API and could surface spurious 404s even though the durable workflow was running fine.
+  - `Run.resumeAsync()` added to core: dispatches the resume in the background and returns `{ runId }` immediately. Engines that poll for results (Inngest) override it to skip polling entirely.
+  - `InngestRun.resumeAsync()` sends the resume event and returns `{ runId }`, skipping polling. Send-time failures (bad payload, event send failure) still reject synchronously and roll back the snapshot.
+  - New `POST /workflows/:workflowId/resume-no-wait` and `POST /agent-builder/:actionId/resume-no-wait` routes return `{ runId }` immediately.
+  - New client SDK `run.resumeNoWait()` resolves with `{ runId }`.
+
+  The existing `resumeAsync()` client/server surface is unchanged and still resolves with the full workflow result, so there is no breaking change.
+
+  `resumeNoWait` is intentionally additive in v1. In Mastra v2 the fire-and-forget behavior is planned to become the default behavior of `resumeAsync()` (mirroring `start`/`resume` semantics), at which point `resumeNoWait` and the `resume-no-wait` routes will be removed. The code paths carry `TODO(v2)` comments documenting this consolidation.
+
+### Patch Changes
+
+- Workflows now support an optional `metadata` field for attaching custom key-value data such as `displayName`, `author`, or `category`. Metadata is preserved through serialization and returned in workflow info API responses. ([#17355](https://github.com/mastra-ai/mastra/pull/17355))
+
+  ```typescript
+  // Define a workflow with metadata
+  const myWorkflow = createWorkflow({
+    id: 'data-processing',
+    metadata: {
+      displayName: 'Data Processing Pipeline',
+
+      category: 'ETL',
+    },
+    inputSchema: z.object({ ... }),
+    outputSchema: z.object({ ... }),
+  });
+
+  // Retrieve workflow info with metadata via the Mastra Server API
+  const workflowInfo = await mastraClient.getWorkflow('data-processing');
+  console.log(workflowInfo.metadata?.displayName); // "Data Processing Pipeline"
+  ```
+
+- Updated dependencies [[`00eca42`](https://github.com/mastra-ai/mastra/commit/00eca4252393aa114dc8c9a5e1da68df91fa06cf), [`8ace89d`](https://github.com/mastra-ai/mastra/commit/8ace89df77f762e622d3b9f7f65ad7524350d050), [`fa63872`](https://github.com/mastra-ai/mastra/commit/fa6387280954e6b667bec5714b55ba082bc627ff), [`f07b646`](https://github.com/mastra-ai/mastra/commit/f07b64604ab7d25391179790b7fd4823df9e2dff), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`40f9297`](https://github.com/mastra-ai/mastra/commit/40f9297003b921c62373d3e8d3a4bda76c9f6de3), [`0f0d1ba`](https://github.com/mastra-ai/mastra/commit/0f0d1ba67bfcb2204e571401662f1eceefc03357), [`8c31bcd`](https://github.com/mastra-ai/mastra/commit/8c31bcdb00e597880d5939b1b7d7566fbe5dacae), [`95b14cd`](https://github.com/mastra-ai/mastra/commit/95b14cdd820e86d97ac05fe568424c513a252e31), [`aa36be2`](https://github.com/mastra-ai/mastra/commit/aa36be23aa513b7dc53cb8ca16b7fab8f20e43ad), [`212c635`](https://github.com/mastra-ai/mastra/commit/212c635203e61d036ab41db8ff86c3893dc795b3), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`9aa5a73`](https://github.com/mastra-ai/mastra/commit/9aa5a73e7e110f6e9365eec69364a33d5f03bb56), [`f73c789`](https://github.com/mastra-ai/mastra/commit/f73c789e8ef21561580395d2c410119cab5848c8), [`8bd16da`](https://github.com/mastra-ai/mastra/commit/8bd16da73a4cb874d739373643dbd6a6e7f88684), [`c8630f8`](https://github.com/mastra-ai/mastra/commit/c8630f80d4f40cb5d22e60ab162b618b1907167a), [`47f71dc`](https://github.com/mastra-ai/mastra/commit/47f71dc6fbcbd12d71e21a979e676e20a02bd77d), [`50ceae2`](https://github.com/mastra-ai/mastra/commit/50ceae270878e2f8fb2b2c6c2faab09df0007c8a), [`8cdde58`](https://github.com/mastra-ai/mastra/commit/8cdde5875bbba6702d9df226f2b20232b8d75d6c), [`847ff1e`](https://github.com/mastra-ai/mastra/commit/847ff1e0d94368d94b2e173e4e0908e115568ef3), [`259d409`](https://github.com/mastra-ai/mastra/commit/259d409a514174299dbde1ff5e1121209b3ba850), [`9e16c68`](https://github.com/mastra-ai/mastra/commit/9e16c6818b6485ccb43df28aba6f3a2219d28662), [`cefca33`](https://github.com/mastra-ai/mastra/commit/cefca33ae666e69810c935fedf95a929c173d1d7), [`d00e8c5`](https://github.com/mastra-ai/mastra/commit/d00e8c50daebe5bce5bf2f48bde39c86fc3d2fe4), [`36fa7e2`](https://github.com/mastra-ai/mastra/commit/36fa7e24d14e58a1eb46147097b32f583e5b8775), [`87e9774`](https://github.com/mastra-ai/mastra/commit/87e97741c1e493cd6d62f478eb810b49bda4d57c), [`65a72e7`](https://github.com/mastra-ai/mastra/commit/65a72e70c25eedea8ff985a6624b96be2850236b), [`0f77241`](https://github.com/mastra-ai/mastra/commit/0f7724108806703799a8ba80ad0f09414afd5066), [`92ff509`](https://github.com/mastra-ai/mastra/commit/92ff5098ef8a990438ca038077021a5f7541ec1d), [`3fce5e7`](https://github.com/mastra-ai/mastra/commit/3fce5e70d011d289043e75003ef3336ed4aa43c3), [`a763592`](https://github.com/mastra-ai/mastra/commit/a763592c3db46963ef1011cfe16fe372816e775e), [`80c7737`](https://github.com/mastra-ai/mastra/commit/80c7737e32d7917b5f356957d67c169d01744fd3), [`3f1cf47`](https://github.com/mastra-ai/mastra/commit/3f1cf476f74c1e4cc2df908837e05853a5347e31), [`ff9d743`](https://github.com/mastra-ai/mastra/commit/ff9d743f71d7e072927725c0d700632aca0c1fee)]:
+  - @mastra/schema-compat@1.2.11-alpha.0
+  - @mastra/core@1.38.0-alpha.3
+
 ## 1.21.2-alpha.2
 
 ### 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.2-alpha.2"
+  version: "1.22.0-alpha.3"
 ---
 
 ## When to use
@@ -17,7 +17,7 @@ Read the individual reference documents for detailed explanations and code examp
 ### Docs
 
 - [A2A](references/docs-agents-a2a.md) - Expose and call remote Mastra agents over the Agent-to-Agent protocol.
-- [Signals](references/docs-agents-signals.md) - Learn how to send real-time context into a Mastra agent thread.
+- [Signals](references/docs-agents-signals.md) - Learn how to send real-time messages and 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.21.2-alpha.2",
+  "version": "1.22.0-alpha.3",
   "package": "@mastra/client-js",
   "exports": {
     "RequestContext": {

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

@@ -2,13 +2,13 @@
 
 > **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
-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 way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle, drops input into the running agent loop, or queues input for the next turn.
 
-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.
+Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 
 ## 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.
+Subscribe to the thread before sending messages. The subscription receives the active stream when the message wakes the agent or enters a running loop.
 
 ```typescript
 const subscription = await agent.subscribeToThread({
@@ -16,33 +16,65 @@ const subscription = await agent.subscribeToThread({
   threadId: 'thread_456',
 })
 
-agent.sendSignal(
+agent.sendMessage('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, `sendMessage()` becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the message as the first input.
+
+## Send a message now
+
+Use `sendMessage()` when the user expects the active agent to see the message immediately.
+
+```typescript
+agent.sendMessage(
   {
-    type: 'user-message',
-    contents: 'Compare that with the previous option.',
+    contents: 'Use the latest customer note too.',
+    attributes: { name: 'Jane', sentFrom: 'slack' },
   },
   {
     resourceId: 'user_123',
     threadId: 'thread_456',
   },
 )
+```
 
-for await (const chunk of subscription.stream) {
-  console.log(chunk)
-}
+The model receives attributed messages as XML-wrapped user input:
+
+```xml
+<user name="Jane" sentFrom="slack">Use the latest customer note too.</user>
+```
+
+Messages without attributes are sent as plain user input.
+
+## Queue a message for the next turn
+
+Use `queueMessage()` when a user sends a follow-up but the active model call should finish first. Mastra waits for the active run to complete, then starts a new run on the same thread.
+
+```typescript
+agent.queueMessage('Also check whether the tests need updates.', {
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
 ```
 
-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.
+When the thread is idle, `queueMessage()` starts a run immediately. When the thread is active, it preserves turn order by starting a new run after the active run completes.
 
-## Control signal behavior
+## Control low-level signal behavior
 
-By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
+Use `sendSignal()` when you need to send system-generated context instead of user-authored input. For external events, use `type: 'notification'`. 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.',
+    type: 'notification',
+    contents: 'GitHub CI failed on PR #123: 3 tests failed.',
   },
   {
     resourceId: 'user_123',
@@ -58,44 +90,43 @@ 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.
+- `ifActive.behavior: 'deliver'`: Add the signal or message to the running agent loop. This is the default.
+- `ifActive.behavior: 'persist'`: Save the signal or message to memory without adding it to the running loop.
+- `ifActive.behavior: 'discard'`: Ignore the signal or message while the thread is active.
+- `ifIdle.behavior: 'wake'`: Start a stream with the signal or message as the first input. This is the default.
+- `ifIdle.behavior: 'persist'`: Save the signal or message to memory without starting a stream.
+- `ifIdle.behavior: 'discard'`: Ignore the signal or message 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,
-      },
+agent.sendMessage('Continue with the next step.', {
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
     },
   },
-)
+})
 ```
 
-## Identify users with attributes
+## Send notification context
+
+Signals have a semantic `type` and an LLM-facing `tagName`. Use `type` to describe the signal category. Use `tagName` to control the XML tag the model sees.
 
-Use `attributes` to tag each signal with user identity. The signal type and attributes are rendered as XML so the model can distinguish who said what in a multi-user thread:
+For external events, use `type: 'notification'`. Reactive signals are reserved for processor- or runtime-generated context, such as policy guidance, background task results, and auto-loaded instructions.
 
 ```typescript
 agent.sendSignal(
   {
-    type: 'user',
-    contents: 'Can we simplify the API surface?',
-    attributes: { name: 'Devin', from: 'slack' },
+    type: 'notification',
+    contents: 'PR #123 has a new review comment from User X about the API surface.',
+    attributes: {
+      source: 'github',
+      pr: '123',
+    },
   },
   {
     resourceId: 'user_123',
@@ -104,51 +135,67 @@ agent.sendSignal(
 )
 ```
 
-The model receives:
+The model receives the signal as context like this:
 
 ```xml
-<user name="Devin" from="slack">Can we simplify the API surface?</user>
+<notification source="github" pr="123">PR #123 has a new review comment from User X about the API surface.</notification>
 ```
 
-The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+Use XML-safe `tagName` and attribute names. They can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
+
+## Send processor context
 
-## Send external event context
+Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
 
-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.
+The following example demonstrates a processor that injects `AGENTS.md` instructions after a tool call reads an `AGENTS.md` file.
 
 ```typescript
-agent.sendSignal(
-  {
-    type: 'system-reminder',
-    contents: 'User X has left a new PR comment asking for a smaller API surface.',
-    attributes: {
-      source: 'github',
-      pr: '123',
-    },
-  },
-  {
-    resourceId: 'user_123',
-    threadId: 'thread_456',
+import type { Processor, ProcessInputStepArgs } from '@mastra/core/processors'
+
+export const agentsMdReminderProcessor: Processor = {
+  id: 'agents-md-reminder',
+  async processInputStep({ messageList, sendSignal }: ProcessInputStepArgs) {
+    const messages = messageList.get.all.db()
+    const agentsMdPath = findAgentsMdPathFromToolCalls(messages)
+
+    if (!agentsMdPath || hasAlreadySentAgentsMdReminder(messages, agentsMdPath)) {
+      return messageList
+    }
+
+    await sendSignal?.({
+      type: 'reactive',
+      contents: readAgentsMdInstructions(agentsMdPath),
+      attributes: {
+        type: 'dynamic-agents-md',
+        path: agentsMdPath,
+      },
+      metadata: {
+        path: agentsMdPath,
+      },
+    })
+
+    return messageList
   },
-)
+}
 ```
 
-The model receives the custom signal as context like this:
+Reactive signals default to `tagName: 'system-reminder'`, so the model receives this context as
 
 ```xml
-<system-reminder source="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+<system-reminder type="dynamic-agents-md" path="packages/ui/AGENTS.md">
+  $agentsMdFileContents
+</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.
+Awaiting `sendSignal()` preserves stream echo ordering when a subscribed thread is active.
 
-## Delivery attributes
+## Conditional attributes
 
-Use `ifActive.attributes` and `ifIdle.attributes` to tag a signal with context that depends on whether the agent is active or idle at delivery time. Mastra resolves the correct branch when the signal is accepted.
+Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Mastra resolves the correct branch when the input is accepted.
 
 ```typescript
-agent.sendSignal(
+agent.sendMessage(
   {
-    type: 'user-message',
     contents: 'Also cover the edge cases.',
     attributes: { source: 'chat' },
   },
@@ -156,7 +203,7 @@ agent.sendSignal(
     resourceId: 'user_123',
     threadId: 'thread_456',
     ifActive: { attributes: { delivery: 'while-active' } },
-    ifIdle: { attributes: { delivery: 'message' } },
+    ifIdle: { attributes: { delivery: 'new-message' } },
   },
 )
 ```
@@ -164,24 +211,35 @@ agent.sendSignal(
 When the agent is working, the model sees:
 
 ```xml
-<user-message source="chat" delivery="while-active">Also cover the edge cases.</user-message>
+<user source="chat" delivery="while-active">Also cover the edge cases.</user>
 ```
 
 When the agent is idle:
 
 ```xml
-<user-message source="chat" delivery="message">Also cover the edge cases.</user-message>
+<user source="chat" delivery="new-message">Also cover the edge cases.</user>
 ```
 
-Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `ifActive.attributes` branch merges when the signal is delivered to a running agent loop. The `ifIdle.attributes` branch merges when the signal wakes an idle thread. If the selected branch or its `attributes` field is `undefined`, no extra attributes are added.
+Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example, you can add any attribute names that suit your use case.
+
+## Compatibility
+
+Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `type: 'system-reminder'`. It normalizes them internally to the new category and tag shape:
+
+- `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
+- `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
+
+Existing stored signal rows and older clients continue to load through the compatibility layer.
+
+> **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
-Delivery attributes work with any signal type and can carry any key-value pairs. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example; you can use any attribute names that fit your application.
+## Use HTTP routes
 
-> **Note:** Visit [Agent.sendSignal() reference](https://mastra.ai/reference/agents/agent) for the full signal input and options types.
+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.
 
 ## 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.
+The JavaScript client exposes thread signal APIs. Use `subscribeToThread()` before sending thread input so the client can render the stream that wakes from, or receives, the input.
 
 ```typescript
 const agent = client.getAgent('supportAgent')
@@ -230,7 +288,10 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 
 ## Related
 
+- [`Agent.sendMessage()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`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)

package/dist/index.cjs

@@ -3185,6 +3185,35 @@ var Run = class extends BaseResource {
       }
     }).then(deserializeWorkflowError);
   }
+  /**
+   * Resumes a suspended workflow step without waiting for the workflow to complete (fire-and-forget)
+   * and returns immediately with the runId. The workflow continues executing in the background.
+   *
+   * Use this when you want to dispatch a resume and return immediately (e.g. an HTTP handler that
+   * never needs the resolved result inline). For Inngest-backed workflows this also avoids the
+   * `getRunOutput()` polling race that `resumeAsync()` can hit.
+   *
+   * TODO(v2): in Mastra v2 this fire-and-forget behavior should become the behavior of
+   * `resumeAsync()` (to mirror `start`/`resume` fire-and-forget semantics), and this method
+   * should be removed. Kept as a separate method in v1 to avoid a breaking contract change.
+   *
+   * @param params - Object containing the step, resumeData and requestContext
+   * @returns Promise containing the runId of the resumed workflow run
+   */
+  resumeNoWait(params) {
+    const requestContext = parseClientRequestContext(params.requestContext);
+    return this.request(`/workflows/${this.workflowId}/resume-no-wait?runId=${this.runId}`, {
+      method: "POST",
+      body: {
+        step: params.step,
+        resumeData: params.resumeData,
+        requestContext,
+        tracingOptions: params.tracingOptions,
+        perStep: params.perStep,
+        forEachIndex: params.forEachIndex
+      }
+    });
+  }
   /**
    * Resumes a suspended workflow step that uses stream asynchronously and returns a promise that resolves when the workflow is complete
    * @param params - Object containing the step, resumeData and requestContext