@mastra/client-js 1.54.1-alpha.4 → 1.55.0-alpha.6

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.54.1-alpha.4"
+  version: "1.55.0-alpha.6"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.54.1-alpha.4",
+  "version": "1.55.0-alpha.6",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-harness-agent-controller.md

@@ -431,6 +431,7 @@ channels: {
 
     return controller.createSession({
       resourceId: thread.resourceId,
+      threadId: thread.id,
       scope: install.id,
       ownerId: controller.id,
       requestContext,
@@ -439,7 +440,7 @@ channels: {
 }
 ```
 
-Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
+Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
 
 Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
 

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

@@ -100,6 +100,26 @@ agent.queueMessage('Also check whether the tests need updates.', {
 
 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.
 
+### Queue a typed signal for the next turn
+
+Use `queueSignal()` when system-generated input needs the same turn ordering as `queueMessage()` but should keep its own signal type, tag, and attributes. For example, a skill invocation can render as a `<skill>` element instead of a plain user message:
+
+```typescript
+agent.queueSignal(
+  {
+    type: 'reactive',
+    tagName: 'skill',
+    attributes: { name: 'triage' },
+    contents: 'Triage the new issue.',
+  },
+  { resourceId: 'user_123', threadId: 'thread_456' },
+)
+```
+
+The model receives `<skill name="triage">Triage the new issue.</skill>`. Queued signals share the `queueMessage()` queue, so they count toward queue-count events and you can cancel them with `cancelQueuedMessages()`.
+
+When a signal starts a run, the run's `AGENT_RUN` span records the signal's `id`, `type`, `tagName`, and `attributes` under `attributes.signal`.
+
 ### Cancel pending input
 
 Use [`cancelQueuedMessages()`](https://mastra.ai/reference/agents/agent) to remove selected pending input without stopping the active run. Cancellation is scoped to the memory thread, including input submitted by other Agents sharing the same runtime and PubSub instance.
@@ -508,12 +528,14 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 
 - [`Agent.sendMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.queueSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendStateSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
 - [`createNotificationInboxTool()`](https://mastra.ai/reference/signals/create-notification-inbox-tool)
 - [`client.getAgent().sendMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().queueMessage()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().queueSignal()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)

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

@@ -213,6 +213,23 @@ await agent.queueMessage({
 })
 ```
 
+### `queueSignal()`
+
+Queue a typed signal for the next thread turn. It follows the same ordering as `queueMessage()`, but keeps the signal's `type`, `tagName`, and `attributes`.
+
+```typescript
+await agent.queueSignal({
+  signal: {
+    type: 'reactive',
+    tagName: 'skill',
+    attributes: { name: 'triage' },
+    contents: 'Triage the new issue.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+```
+
 ### `sendSignal()`
 
 Send a lower-level signal to an active agent run or memory thread. Use this for system-generated context such as reactive reminders or notification-shaped context that doesn't need inbox storage. For durable notification records, use the server-side [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent) API. For user-authored input, prefer `sendMessage()` or `queueMessage()`.

package/dist/index.cjs

@@ -1010,6 +1010,9 @@ var Agent = class extends BaseResource {
 	sendSignal(params) {
 		return this.requestSignalRoute(`/agents/${this.agentId}/signals`, params);
 	}
+	queueSignal(params) {
+		return this.requestSignalRoute(`/agents/${this.agentId}/queue-signal`, params);
+	}
 	async subscribeToThread(params) {
 		const { resourceId, threadId, withInitialHistory } = params;
 		const requestSubscription = () => this.request(`/agents/${this.agentId}/threads/subscribe`, {