@mastra/client-js 1.48.1-alpha.0 → 1.49.0-alpha.2

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.48.1-alpha.0"
+  version: "1.49.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.48.1-alpha.0",
+  "version": "1.49.0-alpha.2",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

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

@@ -90,6 +90,37 @@ 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.
 
+### 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.
+
+The thread must still have a pending message to cancel. This example assumes a run is active when you queue the message. An idle thread starts the message immediately instead.
+
+```typescript
+const queued = agent.queueMessage('Also check the tests.', thread)
+await queued.accepted
+
+const { cancelledSignalIds } = agent.cancelQueuedMessages({
+  ...thread,
+  signalIds: [queued.signal.id],
+})
+console.log(cancelledSignalIds)
+```
+
+Only IDs removed locally by this call appear in `cancelledSignalIds`. Mastra still publishes every requested ID through PubSub, even when none are pending locally, so other processes subscribed to the thread can cancel their matching pending input. Because that propagation is asynchronous, the result doesn't confirm remote cancellation, and input that has already been handed to execution is out of reach. Cancellation doesn't delete saved messages, notification records, or state updates, and it never revokes an earlier acceptance acknowledgement.
+
+### Stop the run and clear pending input
+
+By default, aborting a thread preserves its queued input. To clear pending signals before stopping the active run, pass `clearPendingSignals: true`:
+
+```typescript
+subscription.abort({ clearPendingSignals: true })
+```
+
+Without a subscription, use `agent.abortThreadStream({ ...thread, clearPendingSignals: true })`. Existing listeners stay subscribed after cancellation, and later messages can still start a new run.
+
+With a shared PubSub backend, the runtime receives remote signals, cancellation, and abort requests independently of `subscribeToThread()` observers. Clear-on-abort sends the clear flag to a remote active owner through PubSub, but it doesn't clear every process's local queues. Neither operation cancels continuations created by `continueWithMessages()`.
+
 ## Signal context
 
 ### Control low-level signal behavior

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

@@ -310,6 +310,52 @@ await subscription.processDataStream({
 
 **processDataStream().reconnect** (`boolean | { maxRetries?: number; delayMs?: number }`): Reconnects the subscription stream after it closes or a reconnect request fails. true retries indefinitely with a one-second delay.
 
+The subscription also exposes `abort(options?)` and `unsubscribe()`. `await subscription.abort({ clearPendingSignals: true })` requests an abort and clears pending signals without closing the subscription. Omit the flag to preserve pending input. `unsubscribe()` closes the subscription without aborting the run.
+
+### `abortThread()`
+
+Requests cancellation of the thread's active run. Set `clearPendingSignals: true` to clear pending signals before aborting.
+
+```typescript
+const { aborted } = await agent.abortThread({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  clearPendingSignals: true,
+})
+```
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread to abort.
+
+**clearPendingSignals** (`boolean`): Clear pending signals across Agents sharing the thread before aborting. Continuations from continueWithMessages() are excluded. (Default: `false`)
+
+Returns `{ aborted: boolean }`. For a remote active owner, `aborted: true` means the request was sent, not acknowledged. Clear-on-abort affects the receiving server's local queues and is forwarded to the active owner. It isn't a global queue clear. Local pending signals are still cleared if no active run is found and `aborted` is `false`.
+
+### `cancelQueuedMessages()`
+
+Cancels selected pending signals without stopping the active run. The operation covers pending input across Agents sharing the same memory thread on the server process handling this request. Unlike the core method, the SDK accepts only signal IDs, not `queueOwnerId`.
+
+```typescript
+const { cancelledSignalIds } = await agent.cancelQueuedMessages({
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  signalIds: ['signal-123', 'signal-456'],
+})
+```
+
+**resourceId** (`string`): Resource ID for the memory thread.
+
+**threadId** (`string`): Thread containing the pending signals.
+
+**signalIds** (`string[]`): Between 1 and 1,000 nonempty signal IDs. Duplicate and unknown IDs are ignored.
+
+Returns `{ cancelledSignalIds: string[] }` with each ID cancelled on the receiving server process once. The response doesn't include remote acknowledgements. Signals already handed to execution or another owner aren't included. Missing, empty, or oversized ID lists return HTTP 400. Thread ownership restrictions apply to both cancellation routes.
+
+The server publishes all requested IDs through its shared PubSub backend, even when none are pending on the receiving process. Other subscribed instances can then remove matching pending input, but this best-effort, asynchronous propagation doesn't confirm remote cancellation. Cancellation doesn't undo saved messages, state updates, notification records, or acceptance acknowledgements. It doesn't cancel continuations from `continueWithMessages()`.
+
+The server must use a core version supporting thread-wide cancellation and clear-on-abort. Upgrade `@mastra/core` alongside `@mastra/server`. Unsupported requests return HTTP 501 rather than using older cancellation behavior. With fine-grained authorization enabled, both cancellation routes require `memory:write` permission on the thread in addition to Agent execution permission.
+
 ### `streamUntilIdle()`
 
 Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/harness/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 uses a plain `stream()`.

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

@@ -140,7 +140,7 @@ Returns `Promise<DatasetExperiment>`, the updated experiment record.
 
 ## deleteDatasetExperiment()
 
-Deletes an experiment through its dataset. The server deletes the experiment's result records and attempts to delete its observability traces, including their spans and trace-linked signals, but unsupported storage leaves the traces in place and causes the server to log a warning. If trace cleanup fails after an earlier batch succeeds, the promise rejects and preserves the experiment and result records even though some traces may already have been removed.
+Deletes an experiment through its dataset. The server deletes the experiment's observability traces, including their spans and trace-linked signals, and then deletes the experiment and its result records. Unsupported storage leaves the traces in place, and the server logs a warning. If trace deletion fails for any other reason, the promise rejects and Mastra keeps the experiment and its result records, although some traces may already have been removed.
 
 ```typescript
 await client.deleteDatasetExperiment('dataset-id', 'experiment-id', {
@@ -161,7 +161,7 @@ Returns `Promise<{ success: boolean }>`. A missing experiment, an experiment ass
 
 ## deleteExperiment()
 
-Deletes an experiment by ID without requiring a dataset reference. Use this method for experiments orphaned by dataset deletion. The server deletes the experiment's result records and attempts to delete its observability traces, but unsupported storage leaves the traces in place and causes the server to log a warning. If trace cleanup fails after an earlier batch succeeds, the promise rejects and preserves the experiment and result records even though some traces may already have been removed.
+Deletes an experiment by ID without requiring a dataset reference. Use this method for experiments orphaned by dataset deletion. The server deletes the experiment's observability traces and then deletes the experiment and its result records. Unsupported storage leaves the traces in place, and the server logs a warning. If trace deletion fails for any other reason, the promise rejects and Mastra keeps the experiment and its result records, although some traces may already have been removed.
 
 ```typescript
 await client.deleteExperiment('experiment-id', {
@@ -189,7 +189,7 @@ await client.purgeDatasetItem('dataset-id', 'item-id', {
 })
 ```
 
-The optional third argument scopes the purge to a tenant organization and project. The server returns `404` when the dataset doesn't belong to that scope.
+The optional third argument scopes the purge to a tenant organization and project. The server returns `404` when the dataset doesn't belong to that scope or the item has no history in the dataset.
 
 Returns `Promise<{ success: boolean }>`. The operation is idempotent and can't be undone. Purge serializes or conflicts with concurrent dataset item writers without guaranteeing which operation completes first. If a mutating item update loses the race, storage re-reads the purge marker and rejects it with `DATASET_ITEM_PURGED`. Deletes remain idempotent, and any deletion tombstone created during the race stays redacted. MongoDB storage requires a replica set or sharded deployment with transaction support. See [`dataset.purgeItem()`](https://mastra.ai/reference/datasets/purgeItem) for the complete purge behavior.
 

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

@@ -229,7 +229,7 @@ const result = await mastraClient.deleteTraces({
 console.log(result.success)
 ```
 
-Each request accepts up to 1,000 trace IDs. Signals that aren't linked to a trace are preserved. Deletion also includes traces created by experiments.
+Each request accepts up to 1,000 trace IDs and no tenant scope fields. Signals that aren't linked to a trace are preserved. Traces created by experiments are deleted like any other trace.
 
 ## Scoring traces
 

package/dist/docs/references/reference-observability-tracing-trace-query.md

@@ -217,7 +217,7 @@ Value suggestions are available for these canonical fields:
 
 | Scope    | Fields                                                                        |
 | -------- | ----------------------------------------------------------------------------- |
-| Trace    | `entityName`, `entityType`, `environment`, `status`                           |
+| Trace    | `entityName`, `entityType`, `environment`, `status`, `tags`                   |
 | Spans    | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityName` |
 | Scores   | `scorerId`, `scorerVersion`, `scoreSource`                                    |
 | Feedback | `feedbackType`, `feedbackSource`                                              |
@@ -287,7 +287,8 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
 | Trace             | `traceId`, `threadId`, `resourceId`, `entityName`, `entityType`, `environment`, `status`                                                                     | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace metadata    | `metadata.<key>`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace             | `startedAt`, `endedAt`                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Trace             | `startedAt`, `endedAt`, `durationMs`                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Trace             | `tags`                                                                                                                                                       | `includes`, `notIncludes`, `exists`, `notExists`                           |
 | Span              | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Span              | `startedAt`, `endedAt`, `durationMs`                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Span              | `error`                                                                                                                                                      | `exists`, `notExists`                                                      |
@@ -298,10 +299,26 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
 | Feedback          | `value`, `timestamp`                                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Feedback          | `comment`                                                                                                                                                    | `exists`, `notExists`                                                      |
 
-Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`.
+Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`. Tag predicates name the stored tag collection in `path`. `includes` and `notIncludes` also take one tag in `value`, while `exists` and `notExists` take only `op` and `path`. See [Filter by tags](#filter-by-tags).
 
 String comparisons are case-sensitive, and literals are never coerced. Canonical string fields compare exact stored values. Metadata string values are trimmed before comparison, as described below. Numeric predicates, including `score` and `durationMs`, require numbers, while timestamp predicates require ISO timestamp strings. A missing value satisfies neither positive nor ordered predicates, although it does satisfy the negative operators `ne` and `notIn`. Combine a negative predicate with `exists` when the field must also be present.
 
+### Filter by root duration
+
+At trace scope, `durationMs` is the current completed root span's elapsed time in milliseconds. The value is derived from `endedAt - startedAt` when the query runs:
+
+```typescript
+const slowRootTraces = {
+  op: 'gt',
+  left: { path: 'durationMs' },
+  right: { literal: 5000 },
+}
+```
+
+This top-level predicate doesn't inspect child spans. In contrast, `spans.some` with a `durationMs` predicate examines the current root span and current child spans, so a long child can satisfy that clause even when its root is shorter.
+
+Trace queries exclude incomplete roots before evaluating predicates. As a result, `{ op: 'notExists', path: 'durationMs' }` doesn't find running traces or malformed roots without a usable `endedAt`.
+
 ### Filter by span properties
 
 Every condition inside one `spans.some` or `spans.none` clause applies to the same current span. For example, this predicate finds a failed tool span whose name is `medication_lookup`; a matching name on one span and an error on another don't satisfy it:
@@ -456,6 +473,32 @@ The key must name one top-level property. Empty keys and nested paths are reject
 
 Metadata fields aren't available for grouping. Trace-query discovery returns executable top-level string metadata fields observed in the selected time range.
 
+### Filter by tags
+
+Tags are a list of strings stored on the current root span, so they use collection operators instead of the scalar `in` and `notIn` operators. This query finds production traces tagged for manual review that don't carry the `archived` tag:
+
+```typescript
+const manualReview = {
+  op: 'and',
+  args: [
+    { op: 'eq', left: { path: 'environment' }, right: { literal: 'production' } },
+    { op: 'includes', path: 'tags', value: 'manual-review' },
+    { op: 'notIncludes', path: 'tags', value: 'archived' },
+  ],
+}
+```
+
+| Operator      | Matches when                                              |
+| ------------- | --------------------------------------------------------- |
+| `includes`    | The trace has the requested tag                           |
+| `notIncludes` | The trace has at least one tag, but not the requested tag |
+| `exists`      | The trace has at least one tag                            |
+| `notExists`   | The trace has no tags                                     |
+
+Tags compare exactly and case-sensitively as whole strings. `value` must be one string with at least one non-whitespace character. Combine several `includes` predicates with `and` or `or` to require or allow multiple tags. A trace with no recorded tags and a trace with an empty tag list behave the same: both satisfy `notExists`, neither satisfies `includes`, `notIncludes`, or `exists`. Use `{ op: 'not', arg: { op: 'includes', ... } }` when untagged traces should also match.
+
+`tags` is available in trace predicates only, including those inside `traces.some` or `traces.none`. `in`, `notIn`, and the comparison operators are rejected for `tags`. Value discovery for `tags` returns each observed tag with the number of qualifying traces that carry it.
+
 ### Filter by feedback
 
 Every condition inside one `feedback.some` or `feedback.none` clause applies to the same current feedback record. `feedbackType` and `feedbackSource` are exact application-defined strings rather than built-in enums. This query finds traces with a numeric patient rating below zero:

package/dist/index.cjs

@@ -1019,9 +1019,10 @@ var Agent = class extends BaseResource {
 		const streamResponse = await requestSubscription();
 		if (!streamResponse.body) throw new Error("No response body");
 		const agent = this;
-		streamResponse.abort = async () => (await agent.abortThread({
+		streamResponse.abort = async (options) => (await agent.abortThread({
 			resourceId,
-			threadId
+			threadId,
+			...options
 		})).aborted;
 		let unsubscribed = false;
 		let processAbortController;
@@ -1265,16 +1266,29 @@ var Agent = class extends BaseResource {
 	* @experimental Agent signals are experimental and may change in a future release.
 	*/
 	async abortThread(params) {
-		const { resourceId, threadId, expectedRunId } = params;
+		const { resourceId, threadId, clearPendingSignals, expectedRunId } = params;
 		return this.request(`/agents/${this.agentId}/threads/abort`, {
 			method: "POST",
 			body: {
 				resourceId,
 				threadId,
+				...clearPendingSignals === void 0 ? {} : { clearPendingSignals },
 				...expectedRunId === void 0 ? {} : { expectedRunId }
 			}
 		});
 	}
+	/** @experimental Cancels pending thread signals and propagates requested IDs through shared PubSub. */
+	cancelQueuedMessages(params) {
+		const { resourceId, threadId, signalIds } = params;
+		return this.request(`/agents/${this.agentId}/threads/signals/cancel`, {
+			method: "POST",
+			body: {
+				resourceId,
+				threadId,
+				signalIds
+			}
+		});
+	}
 	/**
 	* Clones this agent to a new stored agent in the database
 	* @param params - Clone parameters including optional newId, newName, metadata, authorId, and requestContext