@mastra/client-js 1.56.0-alpha.6 → 1.56.0-alpha.8

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.56.0-alpha.6"
+  version: "1.56.0-alpha.8"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -321,6 +321,26 @@ await subscription.processDataStream({
 
 Pass `withInitialHistory: true` (or `{ perPage }`) to receive the stored messages as a first `thread-history` chunk instead of fetching history separately. Finished runs aren't replayed after it, so completed answers don't stream again on reconnect.
 
+In the React SDK, `useChat()` exposes the `hasMore` flag from that first page as `initialHistoryPagination`, so you can decide whether to offer loading older messages without another history request:
+
+```typescript
+import { useChat } from '@mastra/react'
+
+const { messages, initialHistoryPagination } = useChat({
+  agentId: 'support-agent',
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  enableThreadSignals: true,
+  withInitialHistory: { perPage: 20 },
+})
+
+// { hasMore: true }: older messages exist
+// { hasMore: false }: the page reaches the start of the thread
+// undefined: history is disabled, still loading, or the subscription ended
+```
+
+`initialHistoryPagination` only describes the initial subscription page for the current agent, resource, thread, and `withInitialHistory` value. It isn't changed by live output or `setMessages()`. After you load older pages yourself, use the `hasMore` value from those responses.
+
 `subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted. Pass `reconnect: true` to resubscribe when the transport closes or a reconnect request fails, such as after a proxy idle timeout. If a reconnect request fails with a 4xx status (for example `401` or `403`) or `501`, `processDataStream()` stops reconnecting and rejects with the original `MastraClientError`. `408` and `429` are still retried.
 
 **resourceId** (`string`): Resource ID for the memory thread.

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

@@ -90,7 +90,7 @@ const result = await mastraClient.querySpans({
 console.log(result.spans)
 ```
 
-Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt` or `endedAt`, ascending or descending, and defaults to descending start time.
+Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, or `timeToFirstChunkMs`, ascending or descending, and defaults to descending start time. Spans without a `timeToFirstChunkMs` value sort last in both directions.
 
 | Fields                                                                                                                                       | Operators                                                                                                  |
 | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -98,7 +98,7 @@ Pages default to 100 rows and allow at most 1,000. The response is `{ spans, pag
 | `organizationId`, `resourceId`, `runId`, `sessionId`, `userId`, `requestId`, `serviceName`, `experimentId`, `environment`, `executionSource` | Same string operators                                                                                      |
 | Entity, parent entity and root entity `Type`, `Id`, `Name`, `VersionId` fields, such as `parentEntityId`                                     | Same string operators                                                                                      |
 | `name`, `spanType`, `status`                                                                                                                 | Same string operators; `name` also accepts `matches` / `notMatches` for normalized whole words and phrases |
-| `startedAt`, `endedAt`, `durationMs`                                                                                                         | Comparisons, membership and presence                                                                       |
+| `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                   | Comparisons, membership and presence                                                                       |
 | `error`                                                                                                                                      | `exists`, `notExists`                                                                                      |
 
 Combine predicates with `and`, `or` and `not`. Membership uses `{ op: 'in', value: { path: 'spanType' }, set: ['agent_run', 'tool_call'] }`. A span's status is `error` when it has an error and `success` otherwise.

package/dist/docs/references/reference-observability-tracing-advanced-queries.md

@@ -21,16 +21,17 @@ For hosted traces, see [Query observability data on Mastra Platform](https://mas
 
 The configured observability store must support each API. Call `getObservabilityCapabilities()` or `GET /api/observability/capabilities` and check these flags before showing a feature:
 
-| Capability                   | Store feature                     | Enables                                                                                |
-| ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `traceQuery`                 | `trace-query`                     | `queryTraces()`                                                                        |
-| `traceAggregate`             | `trace-aggregate`                 | `aggregateTraces()`                                                                    |
-| `traceQueryRootDuration`     | `trace-query-root-duration`       | Trace-scope `durationMs` predicates                                                    |
-| `traceQueryTimeToFirstChunk` | `trace-query-time-to-first-chunk` | `timeToFirstChunkMs` predicates and results                                            |
-| `traceQueryContextIds`       | `trace-query-context-ids`         | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
-| `traceQueryRootSpanFields`   | `trace-query-root-span-fields`    | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
-| `traceQueryDiscovery`        | `trace-query-discovery`           | [Field and value discovery](#discover-fields-and-values)                               |
-| `traceQueryTenantScope`      | `trace-query-tenant-scope`        | [Trusted tenant scope](#trusted-tenant-scope)                                          |
+| Capability                       | Store feature                          | Enables                                                                                |
+| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `traceQuery`                     | `trace-query`                          | `queryTraces()`                                                                        |
+| `traceAggregate`                 | `trace-aggregate`                      | `aggregateTraces()`                                                                    |
+| `traceQueryRootDuration`         | `trace-query-root-duration`            | Trace-scope `durationMs` predicates                                                    |
+| `traceQueryTimeToFirstChunk`     | `trace-query-time-to-first-chunk`      | `timeToFirstChunkMs` predicates and results                                            |
+| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                      |
+| `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
+| `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
+| `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                               |
+| `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                          |
 
 A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name` and `spanType` are the exception and return `422` with a `field_not_allowed` issue.
 
@@ -128,7 +129,13 @@ const slowFirstChunk = {
 
 The value is `null` when the span didn't stream a chunk, for example a tool call or a workflow run. A `null` value counts as missing, so it matches `notExists` and never matches ordered predicates. A value of `0` isn't missing. It means the first chunk arrived in the same millisecond the span started.
 
-Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Sorting by this field isn't supported. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+Trace query results include the root span's `timeToFirstChunkMs`, and `querySpans()` results include each span's value. Stores advertise support through the `trace-query-time-to-first-chunk` feature, and the server reports it as the `traceQueryTimeToFirstChunk` capability. Against an older store, results omit the field, a predicate on it returns `501` before storage runs, and field discovery omits it.
+
+#### Sort by time to first chunk
+
+Pass `orderBy: [{ field: 'timeToFirstChunkMs', direction: 'desc' }]` to list the slowest first chunks first. Traces sort by the root span's value. Missing values sort last in both directions, and `0` sorts as a value. Ties break by `traceId` for traces and by span identity for `querySpans()`.
+
+Stores advertise the sort through the `trace-query-time-to-first-chunk-sort` feature, and the server reports it as the `traceQueryTimeToFirstChunkSort` capability. Against an older store, the sort returns `501` before storage runs.
 
 #### Filter by context identifiers
 
@@ -437,16 +444,16 @@ curl --request POST \
 
 ### Request fields
 
-| Field        | Required | Description                                                                                                                                     |
-| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`. |
-| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                 |
-| `orderBy`    | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode.      |
-| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                            |
-| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                         |
-| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                |
-| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                           |
-| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                            |
+| Field        | Required | Description                                                                                                                                                       |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, and `from` must be earlier than `to`.                   |
+| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans.some` or `spans.none` clauses.                                                                   |
+| `orderBy`    | No       | One item ordering results by `startedAt`, `endedAt`, or `timeToFirstChunkMs`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode. |
+| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                              |
+| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                                           |
+| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                                  |
+| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                                             |
+| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                                              |
 
 Unknown fields are rejected. Requests can't select a projection, declare joins, request counts or measures, or control authorization. Use [`aggregateTraces()`](#aggregate-traces) for counts and measures. Request bodies are limited to 256 KiB.
 

package/dist/index.cjs

@@ -23,8 +23,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let _lukeed_uuid = require("@lukeed/uuid");
 let _mastra_core_error = require("@mastra/core/error");
-let _mastra_schema_compat_schema = require("@mastra/schema-compat/schema");
 let _mastra_core_request_context = require("@mastra/core/request-context");
+let _mastra_schema_compat_schema = require("@mastra/schema-compat/schema");
 let _mastra_schema_compat_zod_to_json = require("@mastra/schema-compat/zod-to-json");
 let _mastra_core_a2a_client = require("@mastra/core/a2a/client");
 let _mastra_core_a2a_v1 = require("@mastra/core/a2a/v1");
@@ -2644,6 +2644,7 @@ var Agent = class extends BaseResource {
 		try {
 			let messages = [];
 			let streamRunId = processedParams.runId;
+			let finishedHistory;
 			const [streamForController, streamForProcessing] = response.body.tee();
 			const decoder = new TextDecoder();
 			let pendingText = "";
@@ -2651,6 +2652,13 @@ var Agent = class extends BaseResource {
 				pendingText += text;
 				const lines = pendingText.split("\n\n");
 				pendingText = isFinal ? "" : lines.pop() ?? "";
+				for (const line of lines) {
+					if (!line.startsWith("data: ") || !line.includes("\"type\":\"finish\"")) continue;
+					try {
+						const all = JSON.parse(line.slice(6))?.payload?.messages?.all;
+						if (Array.isArray(all)) finishedHistory = all;
+					} catch {}
+				}
 				const readableLines = lines.filter((line) => line.trim() !== "[DONE]" && line.trim() !== "data: [DONE]").join("\n\n");
 				if (readableLines) safeEnqueue(new TextEncoder().encode(`${readableLines}\n\n`));
 			};
@@ -2804,12 +2812,12 @@ var Agent = class extends BaseResource {
 								role: "tool",
 								content: toolResultContents
 							};
-							const updatedMessages = threadId ? [toolResultMessage] : [
+							const updatedMessages = threadId ? [toolResultMessage] : (route === "resume-stream" || route === "approve-tool-call" || route === "decline-tool-call") && finishedHistory ? [...finishedHistory, toolResultMessage] : [
 								...Array.isArray(processedParams.messages) ? processedParams.messages : [],
 								...messages,
 								toolResultMessage
 							];
-							const recursionRoute = route === "resume-stream" ? "stream" : route === "resume-stream-until-idle" ? "stream-until-idle" : route;
+							const recursionRoute = route === "resume-stream" || route === "approve-tool-call" || route === "decline-tool-call" ? "stream" : route === "resume-stream-until-idle" ? "stream-until-idle" : route;
 							if (isAborted()) return;
 							try {
 								await this.processStreamResponse({
@@ -3010,7 +3018,8 @@ var Agent = class extends BaseResource {
 		const { requestContext, ...rest } = params;
 		const processedParams = {
 			...rest,
-			requestContext: parseClientRequestContext(requestContext)
+			requestContext: parseClientRequestContext(requestContext),
+			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools)
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
 		const response = await this.processStreamResponse(processedParams, readableController, "approve-tool-call", signal);
@@ -3041,7 +3050,8 @@ var Agent = class extends BaseResource {
 		const { requestContext, ...rest } = params;
 		const processedParams = {
 			...rest,
-			requestContext: parseClientRequestContext(requestContext)
+			requestContext: parseClientRequestContext(requestContext),
+			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools)
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
 		const response = await this.processStreamResponse(processedParams, readableController, "decline-tool-call", signal);
@@ -3198,28 +3208,70 @@ var Agent = class extends BaseResource {
 	* Used when `requireToolApproval` is enabled with generate() to allow the agent to proceed.
 	*/
 	async approveToolCallGenerate(params) {
-		const { requestContext, ...rest } = params;
-		return this.request(`/agents/${this.agentId}/approve-tool-call-generate`, {
+		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
+		const response = await this.request(`/agents/${this.agentId}/approve-tool-call-generate`, {
 			method: "POST",
 			body: {
 				...rest,
-				requestContext: parseClientRequestContext(requestContext)
+				requestContext: parseClientRequestContext(requestContext),
+				clientTools: processClientTools(clientToolsResolver?.() ?? clientTools)
 			}
 		});
+		return this.continueResumedGenerate(response, {
+			requestContext,
+			clientTools,
+			clientToolsResolver,
+			memory
+		});
 	}
 	/**
 	* Declines a pending tool call and returns the complete response (non-streaming).
 	* Used when `requireToolApproval` is enabled with generate() to prevent tool execution.
 	*/
 	async declineToolCallGenerate(params) {
-		const { requestContext, ...rest } = params;
-		return this.request(`/agents/${this.agentId}/decline-tool-call-generate`, {
+		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
+		const response = await this.request(`/agents/${this.agentId}/decline-tool-call-generate`, {
 			method: "POST",
 			body: {
 				...rest,
-				requestContext: parseClientRequestContext(requestContext)
+				requestContext: parseClientRequestContext(requestContext),
+				clientTools: processClientTools(clientToolsResolver?.() ?? clientTools)
 			}
 		});
+		return this.continueResumedGenerate(response, {
+			requestContext,
+			clientTools,
+			clientToolsResolver,
+			memory
+		});
+	}
+	/**
+	* Runs executable client tools the model called after an approval decision and continues on
+	* /generate, like generate() does. With memory the continuation sends only the new messages to the
+	* thread. Without memory it re-sends the conversation up to the last user turn, because the resume
+	* routes keep the earlier history server-side and drop it once the run finishes.
+	*/
+	async continueResumedGenerate(response, { requestContext, clientTools, clientToolsResolver, memory }) {
+		if (response.finishReason !== "tool-calls") return response;
+		const context = requestContext === void 0 || requestContext instanceof _mastra_core_request_context.RequestContext ? requestContext : new _mastra_core_request_context.RequestContext(Object.entries(requestContext));
+		const threadId = typeof memory?.thread === "string" ? memory.thread : memory?.thread?.id;
+		const history = response.messages ?? [];
+		const priorTurns = history.slice(0, history.findLastIndex((message) => message.role === "user") + 1);
+		return executeToolCallAndRespond({
+			response,
+			params: {
+				messages: threadId ? [] : priorTurns,
+				clientTools: clientToolsResolver?.() ?? clientTools,
+				clientToolsResolver,
+				requestContext: context,
+				memory
+			},
+			agentId: this.agentId,
+			resourceId: memory?.resource,
+			threadId,
+			requestContext: context,
+			respondFn: (messages, options) => this.generate(messages, options)
+		});
 	}
 	/**
 	* Processes the stream response and handles tool calls