@mastra/client-js 1.44.1-alpha.2 → 1.45.0-alpha.4

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.44.1-alpha.2"
+  version: "1.45.0-alpha.4"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.44.1-alpha.2",
+  "version": "1.45.0-alpha.4",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

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

@@ -133,6 +133,32 @@ const session = await controller.createSession({
 
 Use [`session.thread.create()`](https://mastra.ai/reference/agent-controller/session) and [`session.thread.switch()`](https://mastra.ai/reference/agent-controller/session) to move one live Session between conversations.
 
+### List stored messages from the client
+
+Use the Agent Controller client to page through a thread's stored messages. Passing an options object returns the messages with pagination metadata:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({ baseUrl: 'http://localhost:4111' })
+const session = client.getAgentController('assistant-controller').session('user-123')
+
+const result = await session.listMessages('support-ticket-42', {
+  page: 0,
+  perPage: 20,
+  orderBy: { field: 'createdAt', direction: 'DESC' },
+  filter: {
+    dateRange: { start: new Date('2026-01-01') },
+  },
+})
+
+console.log(result.messages)
+console.log(result.total)
+console.log(result.hasMore)
+```
+
+`page` is zero-indexed. Omitting `perPage` uses the storage default of 40 messages. Use `include` to request a message by ID with adjacent messages. `limit` is a deprecated alias for `perPage`; existing paged callers may use `{ limit, page }`, but must use `perPage` with `orderBy`, `filter`, or `include`. The existing numeric form, `session.listMessages(threadId, limit)`, remains available when you need the newest message window as an array, ordered oldest-first.
+
 ## Switch modes and models
 
 Modes change the instructions and tools used by the shared backing agent without replacing the Session or thread. Configure mode-specific tools and visibility on the controller:

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

@@ -111,6 +111,9 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
 | Score             | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                                                | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Score             | `score`, `timestamp`                                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Score             | `spanId`                                                                                                                                                     | `exists`, `notExists`                                                      |
+| Feedback          | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                            | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| 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`.
 
@@ -270,6 +273,45 @@ The key must name one top-level property. Empty keys and nested paths are reject
 
 Metadata fields aren't available for grouping or field discovery.
 
+### 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:
+
+```typescript
+const negativePatientRating = {
+  feedback: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'feedbackType' }, right: { literal: 'rating' } },
+        { op: 'eq', left: { path: 'feedbackSource' }, right: { literal: 'patient' } },
+        { op: 'lt', left: { path: 'value' }, right: { literal: 0 } },
+      ],
+    },
+  },
+}
+```
+
+Strict stored-value types are the portable contract for feedback predicates. PostgreSQL and ClickHouse distinguish numeric `3` from textual `'3'` for equality and ordered comparisons. DuckDB currently persists feedback values as `VARCHAR`, so numeric-looking strings may be coerced for equality and ordered numeric predicates. OBS-306 will remove this DuckDB exception through typed persistence. Ordered operators require a finite numeric literal. `eq` and `ne` accept one string or number, while `in` and `notIn` require a non-empty set containing only strings or only numbers. `exists` and `notExists` test for either value type.
+
+Use `none` to select traces without a matching record. Traces with no feedback also match:
+
+```typescript
+const missingClinicianReview = {
+  feedback: {
+    none: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'feedbackType' }, right: { literal: 'clinical-review' } },
+        { op: 'eq', left: { path: 'feedbackSource' }, right: { literal: 'clinician' } },
+      ],
+    },
+  },
+}
+```
+
+Feedback `timestamp` predicates are independent of the root `timeRange`. Use `comment` only with `exists` or `notExists`. Comment contents aren't searchable. The deprecated feedback fields `source` and `userId` aren't available. Use `feedbackSource` and `feedbackUserId`.
+
 ## Responses
 
 An ungrouped query returns only lightweight completed traces:

package/dist/index.cjs

@@ -6179,10 +6179,29 @@ var AgentControllerSession = class extends BaseResource {
 			body: options ?? {}
 		});
 	}
-	/** List messages for a specific thread. */
-	async listMessages(threadId, limit) {
-		const params = limit != null ? `?limit=${limit}` : "";
-		return (await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${params}`))).messages.map(hydrateMessage);
+	async listMessages(threadId, options) {
+		const queryParams = new URLSearchParams();
+		const legacy = typeof options === "number" || options === void 0;
+		if (typeof options === "number") queryParams.set("limit", String(options));
+		else if (options === void 0) queryParams.set("perPage", "false");
+		else {
+			const { limit, page, perPage, orderBy, filter, include } = options;
+			if (limit !== void 0 && (perPage !== void 0 || orderBy !== void 0 || filter !== void 0 || include !== void 0)) throw new Error("limit can only be combined with page; use perPage with orderBy, filter, or include");
+			if (limit !== void 0) queryParams.set("limit", String(limit));
+			if (page !== void 0) queryParams.set("page", String(page));
+			if (perPage !== void 0) queryParams.set("perPage", String(perPage));
+			if (orderBy) queryParams.set("orderBy", JSON.stringify(orderBy));
+			if (filter) queryParams.set("filter", JSON.stringify(filter));
+			if (include) queryParams.set("include", JSON.stringify(include));
+		}
+		const query = queryParams.toString();
+		const body = await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${query ? `?${query}` : ""}`));
+		const messages = body.messages.map(hydrateMessage);
+		if (legacy) return messages;
+		return {
+			...body,
+			messages
+		};
 	}
 	/**
 	* Queue a follow-up message. If the session is idle it sends immediately;