@mastra/client-js 1.46.1-alpha.0 → 1.47.0-alpha.10

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.46.1-alpha.0",
+  "version": "1.47.0-alpha.10",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-connections-a2a.md

@@ -67,7 +67,7 @@ Mastra supports A2A Protocol v0.3 and v1.0 on the same agent card and execution
 - `1.0`: Uses the v1.0 API.
 - Any other value: Returns a `VersionNotSupported` protocol error.
 
-Existing `A2AAgent` and `MastraClient.getA2A()` integrations continue to use v0.3. Use `MastraClient.getA2AV1()` for v1.0 requests. The v1 client sends `A2A-Version: 1.0` automatically and adds the `tasks/list` operation.
+`A2AAgent` and `MastraClient.getA2A()` use v0.3 by default. Set `protocolVersion: '1.0'` on `A2AAgent` for v1.0 subagent delegation, or use `MastraClient.getA2AV1()` for direct v1.0 requests. Both v1.0 clients send `A2A-Version: 1.0` automatically. The direct v1.0 client also adds the `tasks/list` operation.
 
 Import v1.0 protocol types and codecs from `@mastra/core/a2a/v1`. The existing `@mastra/core/a2a/client` export remains on v0.3.
 
@@ -82,7 +82,7 @@ Use `A2AAgent` when another Mastra agent should delegate work to a remote agent.
 
 ## Consume A2A agents as subagents
 
-Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path. Set `protocolVersion: '1.0'` when the remote agent requires A2A v1.0. Omit it to use v0.3.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -90,6 +90,7 @@ import { A2AAgent } from '@mastra/core/a2a'
 
 const remoteWeatherAgent = new A2AAgent({
   url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
+  protocolVersion: '1.0',
   headers: {
     Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
   },
@@ -112,7 +113,7 @@ During execution, `A2AAgent`:
 
 - Fetches and caches the remote agent card.
 - Reads the execution URL and capabilities from the card.
-- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
+- Calls `message/send` or `message/stream` with v0.3, and `SendMessage` or `SendStreamingMessage` with v1.0.
 - Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
 - Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
 

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

@@ -74,8 +74,8 @@ const session = await controller.createSession({
 })
 
 const unsubscribe = session.subscribe(event => {
-  if (event.type === 'message_update') {
-    console.log(event.message)
+  if (event.type === 'message_update' && event.event.type === 'text-delta') {
+    process.stdout.write(event.event.delta)
   }
 })
 
@@ -83,6 +83,8 @@ await session.sendMessage({ content: 'Plan a small TypeScript CLI.' })
 unsubscribe()
 ```
 
+Each message emits a `message_start` event with the initial message, zero or more `message_update` events with compact deltas, and a `message_end` event containing the message ID. Apply updates by ID when you need to reconstruct the complete message.
+
 Use the same controller for many Sessions. Don't store a current Session on the controller or route work through controller-level message methods.
 
 ## Understand the runtime model

package/dist/docs/references/reference-client-js-agent-controller.md

@@ -219,31 +219,92 @@ Returns: `Promise<SendNotificationResult>`
 
 `onEvent` receives every event the session emits, discriminated by `event.type`:
 
-| Group        | Events                                                                                                                                                                                                                                                                                  |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Run          | `agent_start`, `agent_end`, `usage_update`, `goal_evaluation`, `follow_up_queued`                                                                                                                                                                                                       |
-| Messages     | `message_start`, `message_update`, `message_end`                                                                                                                                                                                                                                        |
-| Tools        | `tool_input_start`, `tool_input_delta`, `tool_input_end`, `tool_start`, `tool_update`, `tool_end`, `shell_output`, `command_exit`, `tool_approval_required`, `tool_suspended`, `tool_suspension_cancelled`, `task_updated`                                                              |
-| Session      | `state_changed`, `display_state_changed`, `mode_changed`, `model_changed`, `thread_changed`, `thread_created`, `thread_deleted`, `thread_title_updated`                                                                                                                                 |
-| Subagents    | `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`                                                                                                                                                           |
-| Memory       | `om_observation_start`, `om_observation_end`, `om_observation_failed`, `om_reflection_start`, `om_reflection_end`, `om_reflection_failed`, `om_buffering_start`, `om_buffering_end`, `om_buffering_failed`, `om_model_changed`, `om_activation`, `om_status`, `om_thread_title_updated` |
-| Workspace    | `workspace_ready`, `workspace_error`, `workspace_status_changed`                                                                                                                                                                                                                        |
-| Notification | `notification`, `notification_summary`, `info`, `error`                                                                                                                                                                                                                                 |
+| Group       | Events                                                                                                                                                                                                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run         | `agent_start`, `agent_end`, `usage_update`, `goal_evaluation`, `follow_up_queued`                                                                                                                                                                                                       |
+| Messages    | `message_start`, `message_update`, `message_end`                                                                                                                                                                                                                                        |
+| Tools       | `tool_input_start`, `tool_input_delta`, `tool_input_end`, `tool_start`, `tool_update`, `tool_end`, `shell_output`, `command_exit`, `tool_approval_required`, `tool_suspended`, `tool_suspension_cancelled`, `task_updated`                                                              |
+| Session     | `state_changed`, `display_state_changed`, `mode_changed`, `model_changed`, `thread_changed`, `thread_created`, `thread_deleted`, `thread_title_updated`                                                                                                                                 |
+| Subagents   | `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`                                                                                                                                                           |
+| Memory      | `om_observation_start`, `om_observation_end`, `om_observation_failed`, `om_reflection_start`, `om_reflection_end`, `om_reflection_failed`, `om_buffering_start`, `om_buffering_end`, `om_buffering_failed`, `om_model_changed`, `om_activation`, `om_status`, `om_thread_title_updated` |
+| Workspace   | `workspace_ready`, `workspace_error`, `workspace_status_changed`                                                                                                                                                                                                                        |
+| Diagnostics | `info`, `error`                                                                                                                                                                                                                                                                         |
 
-`message_*` events carry a `MastraDBMessage` and `thread_created` carries a thread, with timestamps hydrated to `Date`.
+Notifications are delivered as agent signals carried on messages rather than as `notification` or `notification_summary` controller events.
 
-A controller can also emit events the SDK doesn't type. `AgentControllerEvent` is the union of `KnownAgentControllerEvent` and `OtherAgentControllerEvent`. Because `OtherAgentControllerEvent.type` is `string`, comparing `event.type` to a literal doesn't narrow the union. Narrow with `isKnownAgentControllerEvent(event)` first:
+A message lifecycle uses three event shapes:
+
+- `message_start` carries the initial `MastraDBMessage`, with `createdAt` hydrated to `Date`.
+- `message_update` carries the message `id` and a compact text, reasoning, or part update.
+- `message_end` carries the `id` of the completed message.
+
+`thread_created` also carries a thread with timestamps hydrated to `Date`.
+
+A controller can emit events the SDK doesn't type. `AgentControllerEvent` is the union of `KnownAgentControllerEvent` and `OtherAgentControllerEvent`. Because `OtherAgentControllerEvent.type` is `string`, comparing `event.type` to a literal doesn't narrow the union. Narrow with `isKnownAgentControllerEvent(event)` first, then reconstruct messages by ID:
 
 ```typescript
-import { isKnownAgentControllerEvent } from '@mastra/client-js'
+import {
+  isKnownAgentControllerEvent,
+  type AgentControllerEvent,
+  type KnownAgentControllerEvent,
+  type MastraDBMessage,
+} from '@mastra/client-js'
+
+type MessageUpdate = Extract<KnownAgentControllerEvent, { type: 'message_update' }>['event']
+
+const activeMessages = new Map<string, MastraDBMessage>()
+
+function applyUpdate(message: MastraDBMessage, update: MessageUpdate): MastraDBMessage {
+  const parts = [...message.content.parts]
+
+  if (update.type === 'text-delta') {
+    const index = parts.findLastIndex(part => part.type === 'text')
+    const part = parts[index]
+
+    if (part?.type === 'text') {
+      parts[index] = { ...part, text: part.text + update.delta }
+    } else {
+      parts.push({ type: 'text', text: update.delta })
+    }
+  } else if (update.type === 'reasoning-delta') {
+    const part = parts[update.index]
+    const reasoning = part?.type === 'reasoning' ? part.reasoning + update.delta : update.delta
+    parts[update.index] = {
+      ...(part?.type === 'reasoning' ? part : { type: 'reasoning' as const }),
+      reasoning,
+      details: [{ type: 'text', text: reasoning }],
+    }
+  } else {
+    parts[update.index] = update.part
+  }
+
+  return { ...message, content: { ...message.content, parts } }
+}
 
 function handleEvent(event: AgentControllerEvent) {
   if (!isKnownAgentControllerEvent(event)) return
 
   switch (event.type) {
-    case 'message_update':
-      render(event.message)
+    case 'message_start':
+      activeMessages.set(event.message.id, structuredClone(event.message))
+      break
+    case 'message_update': {
+      const message = activeMessages.get(event.id)
+      if (!message) break
+
+      const updated = applyUpdate(message, event.event)
+      activeMessages.set(event.id, updated)
+      render(updated)
+      break
+    }
+    case 'message_end': {
+      const message = activeMessages.get(event.id)
+      if (!message) break
+
+      renderComplete(message)
+      activeMessages.delete(event.id)
       break
+    }
     case 'tool_approval_required':
       showApproval(event.toolCallId)
       break
@@ -251,7 +312,7 @@ function handleEvent(event: AgentControllerEvent) {
 }
 ```
 
-Use `agentControllerMessageText(message)` to pull the plain text out of a message's nested content parts.
+Use `agentControllerMessageText(message)` to pull the plain text out of a reconstructed message's nested content parts.
 
 ## Related
 

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

@@ -119,6 +119,31 @@ while (true) {
 }
 ```
 
+#### Cancelling a stream
+
+Cancelling the response body aborts the underlying HTTP request and stops any pending client tool executions and follow-up requests:
+
+```typescript
+const response = await agent.stream('Tell me a story')
+const reader = response.body.getReader()
+
+const { value } = await reader.read()
+await reader.cancel('user navigated away')
+```
+
+You can also pass an `abortSignal` to cancel from outside the stream. The same option is available on `streamUntilIdle()`, `resumeStream()`, `resumeStreamUntilIdle()`, `approveToolCall()`, `declineToolCall()`, `generate()`, and `generateLegacy()`:
+
+```typescript
+const controller = new AbortController()
+
+const response = await agent.stream('Tell me a story', {
+  abortSignal: controller.signal,
+})
+
+// Later
+controller.abort()
+```
+
 #### AI SDK compatible format
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:

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

@@ -81,7 +81,7 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
-**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See Agent Builder API.
+**getAgentBuilderActions()** (`Promise<GetAgentBuilderActionsResponse>`): Returns all available Agent Builder actions. See Agent Builder API.
 
 **getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See Agent Builder API.
 

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

@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
 
 It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
 
-## Querying traces with recursive predicates
+## Querying traces and threads
 
-`queryTraces()` finds completed logical traces using trace fields and conditions over related spans or scores. Every query requires an ISO timestamp range of at most 31 days.
+`queryTraces()` finds completed logical traces using trace fields and conditions over related spans, scores, or feedback. Every query requires an ISO timestamp range of at most 31 days.
 
 ```typescript
 const result = await mastraClient.queryTraces({
@@ -89,9 +89,106 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
-The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse queries have a configurable 15-second execution timeout.
+### Discover trace-query fields and values
 
-See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, grouping, cursor pagination, response shapes, and errors.
+`getTraceQueryFields()` returns canonical query fields and observed top-level string metadata fields for one predicate scope. The response includes each field's value kind, supported operators, and whether value suggestions are available.
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+
+const fields = await mastraClient.getTraceQueryFields({
+  timeRange,
+  predicateScope: 'spans',
+  search: 'model',
+  limit: 25,
+})
+```
+
+Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A global picker can fetch `trace`, `spans`, `scores`, and `feedback` in parallel.
+
+Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
+
+```typescript
+const controller = new AbortController()
+
+const values = await mastraClient.getTraceQueryValues(
+  {
+    timeRange,
+    predicateScope: 'spans',
+    path: 'model',
+    search: 'claude',
+    limit: 25,
+  },
+  { signal: controller.signal },
+)
+
+// Cancel this autocomplete request when the search text changes.
+controller.abort()
+```
+
+Both methods use case-insensitive literal substring search and accept an empty search. Limits default to 25 and can't exceed 100. Results are ordered by occurrence count, then deterministically by path or value. `observedFieldsTruncated` and `valuesTruncated` indicate that the caller should refine `search`. Discovery has no cursor.
+
+Suggestions are bounded and advisory. Manual values remain valid when suggestions are unavailable, empty, or truncated. Discovery doesn't accept a draft query predicate. The client doesn't retry either request, and a per-call `AbortSignal` takes precedence over the signal configured on `MastraClient`.
+
+A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
+
+`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
+
+```typescript
+const result = await mastraClient.queryTraceThreads({
+  traces: {
+    timeRange: {
+      from: '2026-08-01T00:00:00.000Z',
+      to: '2026-08-08T00:00:00.000Z',
+    },
+    where: {
+      op: 'eq',
+      left: { path: 'environment' },
+      right: { literal: 'production' },
+    },
+  },
+  where: {
+    op: 'and',
+    args: [
+      {
+        traces: {
+          some: {
+            scores: {
+              some: {
+                op: 'lt',
+                left: { path: 'score' },
+                right: { literal: 0.6 },
+              },
+            },
+          },
+        },
+      },
+      {
+        traces: {
+          some: {
+            feedback: {
+              some: {
+                op: 'eq',
+                left: { path: 'feedbackType' },
+                right: { literal: 'clinician-correction' },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+})
+
+// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
+```
+
+The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
+
+See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
 
 ## Deleting traces
 
@@ -136,7 +233,7 @@ const scores = await mastraClient.listScoresBySpan({
 
 ## Feedback
 
-Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform feedback query API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
+Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections through the target Mastra runtime and its configured observability storage. They don't call the hosted Mastra Platform Feedback API. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.
 
 ### Creating feedback
 
@@ -188,6 +285,8 @@ const feedback = await mastraClient.listFeedback({
 })
 ```
 
+`filters` accepts every [`FeedbackFilter`](https://mastra.ai/reference/observability/feedback) field. The client sends them as query parameters on `GET /api/observability/feedback`. See [list query parameters](https://mastra.ai/reference/observability/feedback).
+
 ### Aggregating feedback
 
 Aggregate numeric feedback values, such as ratings or thumbs encoded as `1` and `-1`: