@mastra/libsql 1.19.0 → 1.20.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @mastra/libsql
 
+## 1.20.0-alpha.0
+
+### Minor Changes
+
+- Added experiment provenance and grouping support to the LibSQL, MongoDB, MySQL, PostgreSQL, and Spanner storage adapters. These fields remain available for later grouping and filtering. ([#20645](https://github.com/mastra-ai/mastra/pull/20645))
+
+  ```ts
+  import { PostgresStore } from '@mastra/pg';
+
+  const storage = new PostgresStore({
+    id: 'postgres-storage',
+    connectionString: process.env.DATABASE_URL!,
+  });
+
+  await dataset.startExperiment({
+    task,
+    scorers,
+    provenance: { source: 'github', sourceVersion: 'abc123' },
+    grouping: { experimentSetId: 'benchmark-1', variantId: 'candidate', trialIndex: 0 },
+  });
+  ```
+
+- Memory list reads now surface database errors instead of silently returning empty results. ([#17910](https://github.com/mastra-ai/mastra/pull/17910))
+
+  Previously, the paginated memory reads (`listThreads`, `listMessages`, `listMessagesByResourceId`, and `listMessagesById`) caught backend failures, logged them, and returned an empty payload like `{ threads: [], total: 0, hasMore: false }`. A transient outage (locked table, dropped connection) was therefore indistinguishable from a genuinely empty result, so an agent reading conversation history during a brief failure would treat it as "no history" and could overwrite real state. These methods now re-throw the failure as a `MastraError`. Validation (USER) errors and genuinely empty results are unchanged.
+
+  **Behavior change**
+
+  Callers that previously received an empty result on a backend failure will now receive a thrown `MastraError`. If you call these read methods directly (rather than through an agent, which already surfaces errors), wrap them so a transient outage doesn't crash the caller:
+
+  ```ts
+  try {
+    const { threads } = await storage.listThreads({ resourceId });
+    // ...use threads
+  } catch (error) {
+    // a real backend failure. Decide whether to retry, surface, or degrade.
+    // An empty thread list no longer hides here; it only means "no threads".
+  }
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`e7109ee`](https://github.com/mastra-ai/mastra/commit/e7109ee6f731bacc79c885906f3c7dca8d8f013a), [`772c0c8`](https://github.com/mastra-ai/mastra/commit/772c0c897cec383258de2e6178147f8014767c7b), [`578bf2e`](https://github.com/mastra-ai/mastra/commit/578bf2e6a88e9d5b8bf502204e15a95dfbb679ae), [`06b2d87`](https://github.com/mastra-ai/mastra/commit/06b2d87e63bcdd0ed59215c6789692b9b12de376), [`ac01d63`](https://github.com/mastra-ai/mastra/commit/ac01d6355974aec73fdb8781449ed12bac582094), [`a810a05`](https://github.com/mastra-ai/mastra/commit/a810a058f62ad407cfc1701e0be36ae91145d7cf), [`f8da216`](https://github.com/mastra-ai/mastra/commit/f8da21633e7eb0e31c9ce0fc30567870d19416d3), [`6104347`](https://github.com/mastra-ai/mastra/commit/61043473ba6bfd0a25156824e853e13165562e6c), [`45bfb88`](https://github.com/mastra-ai/mastra/commit/45bfb88fd52f1dd3be20e2a38905777c96499c90), [`e3b9307`](https://github.com/mastra-ai/mastra/commit/e3b9307098daefbfae2a52ae2ef51bc9fc701190), [`d6834c5`](https://github.com/mastra-ai/mastra/commit/d6834c5a7866b16734d23900163c2414ed70d791), [`c52d346`](https://github.com/mastra-ai/mastra/commit/c52d3462ec831a5d95926ecd3d3373f5928ad2e5), [`0023e79`](https://github.com/mastra-ai/mastra/commit/0023e7919431078280abd11c89d1edeae35fcc69), [`c2ad51e`](https://github.com/mastra-ai/mastra/commit/c2ad51e2467f901eecba8c9f4a45e22a50bd7c18), [`3dc97ea`](https://github.com/mastra-ai/mastra/commit/3dc97ea415fad353b48a13095fad1835933cc12a), [`3d01cd3`](https://github.com/mastra-ai/mastra/commit/3d01cd387321b6f9c5cac31d487c84bf51b19c78), [`7bf3086`](https://github.com/mastra-ai/mastra/commit/7bf308663f0115ca74ad20554ade740f06640859), [`a8dd139`](https://github.com/mastra-ai/mastra/commit/a8dd1391a9fe9a6632c25809ef236980afa9a020), [`e5786be`](https://github.com/mastra-ai/mastra/commit/e5786be02bb903073082bd9d6da880ebaacc343f), [`2093fbd`](https://github.com/mastra-ai/mastra/commit/2093fbd53bb744bae19ec89f6d73db9a66fbe8a7), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`7b4393d`](https://github.com/mastra-ai/mastra/commit/7b4393d557411fdcf07b0e30e5acaf7cc85154ae)]:
+  - @mastra/core@1.58.0-alpha.1
+
 ## 1.19.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.19.0"
+  version: "1.20.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.19.0",
+  "version": "1.20.0-alpha.0",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-agent-approval.md

@@ -498,7 +498,7 @@ The same discovery is available over HTTP as `GET /agents/:agentId/suspended-run
 
 ## Tool approval: Supervisor agents
 
-A [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
+A [supervisor agent](https://mastra.ai/docs/capabilities/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
 
 1. The supervisor delegates a task to a subagent.
 2. The subagent calls a tool that has `requireApproval: true` or uses `suspend()`.

package/dist/docs/references/docs-agents-networks.md

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
@@ -180,5 +180,5 @@ Requirements for automatic resumption:
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
 - [Migration: `.network()` to supervisor agents](https://mastra.ai/guides/migrations/network-to-supervisor)

package/dist/docs/references/docs-memory-overview.md

@@ -188,7 +188,7 @@ Conversation messages are ordered by timestamp and deduplicated by message ID, s
 
 ## Memory in multi-agent systems
 
-When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+When a [supervisor agent](https://mastra.ai/docs/capabilities/subagents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
 
 ### How delegation scopes memory
 
@@ -200,7 +200,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 
 > **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved, the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved, the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/capabilities/subagents) callback.
 
 > **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Different subagents under the same supervisor never share a resource ID through delegation.
 

package/dist/docs/references/docs-storage-overview.md

@@ -184,7 +184,7 @@ export const mastra = new Mastra({
 })
 ```
 
-You can also route `observability` to a dedicated analytics backend. See [observability storage](https://mastra.ai/docs/observability/storage) for an observability-specific example.
+You can also route `observability` to a dedicated analytics backend. See the [observability quickstart](https://mastra.ai/docs/observability/overview) for an observability-specific example.
 
 ## Supported providers
 
@@ -211,4 +211,4 @@ Each provider page includes installation instructions, configuration parameters,
 - [Storage retention](https://mastra.ai/reference/storage/retention)
 - [Storage schemas](https://mastra.ai/reference/storage/overview)
 - [Memory](https://mastra.ai/docs/memory/overview)
-- [Observability storage](https://mastra.ai/docs/observability/storage)
+- [Observability storage](https://mastra.ai/docs/observability/overview)

package/dist/docs/references/reference-file-based-agents-storage.md

@@ -23,7 +23,7 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Production backends
 
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
 
 ## Precedence with code
 

package/dist/index.cjs

@@ -4592,7 +4592,13 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 			ifNotExists: [
 				"agentVersion",
 				"organizationId",
-				"projectId"
+				"projectId",
+				"provenance",
+				"runnerAttestation",
+				"experimentSetId",
+				"comparisonId",
+				"variantId",
+				"trialIndex"
 			]
 		});
 		await this.#db.alterTable({
@@ -4612,6 +4618,10 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				sql: `CREATE INDEX IF NOT EXISTS idx_experiments_datasetid ON "${_mastra_core_storage.TABLE_EXPERIMENTS}" ("datasetId")`,
 				args: []
 			},
+			{
+				sql: `CREATE INDEX IF NOT EXISTS idx_experiments_grouping ON "${_mastra_core_storage.TABLE_EXPERIMENTS}" ("experimentSetId", "comparisonId", "variantId", "trialIndex")`,
+				args: []
+			},
 			{
 				sql: `CREATE INDEX IF NOT EXISTS idx_experiment_results_experimentid ON "${_mastra_core_storage.TABLE_EXPERIMENT_RESULTS}" ("experimentId")`,
 				args: []
@@ -4711,6 +4721,12 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 			name: row.name ?? void 0,
 			description: row.description ?? void 0,
 			metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : void 0,
+			provenance: row.provenance ? (0, _mastra_core_storage.safelyParseJSON)(row.provenance) : null,
+			runnerAttestation: row.runnerAttestation ? (0, _mastra_core_storage.safelyParseJSON)(row.runnerAttestation) : null,
+			experimentSetId: row.experimentSetId ?? null,
+			comparisonId: row.comparisonId ?? null,
+			variantId: row.variantId ?? null,
+			trialIndex: row.trialIndex != null ? row.trialIndex : null,
 			status: row.status,
 			totalItems: row.totalItems,
 			succeededCount: row.succeededCount,
@@ -4764,6 +4780,12 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 					name: input.name ?? null,
 					description: input.description ?? null,
 					metadata: input.metadata ?? null,
+					provenance: input.provenance ?? null,
+					runnerAttestation: input.runnerAttestation ?? null,
+					experimentSetId: input.experimentSetId ?? null,
+					comparisonId: input.comparisonId ?? null,
+					variantId: input.variantId ?? null,
+					trialIndex: input.trialIndex ?? null,
 					status: "pending",
 					totalItems: input.totalItems,
 					succeededCount: 0,
@@ -4787,6 +4809,12 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				name: input.name,
 				description: input.description,
 				metadata: input.metadata,
+				provenance: input.provenance ?? null,
+				runnerAttestation: input.runnerAttestation ?? null,
+				experimentSetId: input.experimentSetId ?? null,
+				comparisonId: input.comparisonId ?? null,
+				variantId: input.variantId ?? null,
+				trialIndex: input.trialIndex ?? null,
 				status: "pending",
 				totalItems: input.totalItems,
 				succeededCount: 0,
@@ -4912,6 +4940,22 @@ var ExperimentsLibSQL = class extends _mastra_core_storage.ExperimentsStorage {
 				conditions.push("status = ?");
 				queryParams.push(args.status);
 			}
+			if (args.experimentSetId !== void 0) {
+				conditions.push("experimentSetId = ?");
+				queryParams.push(args.experimentSetId);
+			}
+			if (args.comparisonId !== void 0) {
+				conditions.push("comparisonId = ?");
+				queryParams.push(args.comparisonId);
+			}
+			if (args.variantId !== void 0) {
+				conditions.push("variantId = ?");
+				queryParams.push(args.variantId);
+			}
+			if (args.trialIndex !== void 0) {
+				conditions.push("trialIndex = ?");
+				queryParams.push(args.trialIndex);
+			}
 			if (args.filters) {
 				const { organizationId, projectId } = args.filters;
 				if (organizationId !== void 0) {
@@ -6873,6 +6917,7 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 				hasMore: metadataFilter ? perPageInput !== false && offset + paginatedCount < total : perPageInput !== false && !allThreadMessagesReturned && offset + perPage < total
 			};
 		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError && error.category === _mastra_core_error.ErrorCategory.USER) throw error;
 			const mastraError = new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -6884,25 +6929,19 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 			}, error);
 			this.logger?.error?.(mastraError.toString());
 			this.logger?.trackException?.(mastraError);
-			return {
-				messages: [],
-				total: 0,
-				page,
-				perPage: perPageForResponse,
-				hasMore: false
-			};
+			throw mastraError;
 		}
 	}
 	async listMessagesByResourceId(args) {
 		const { resourceId, include, filter, perPage: perPageInput, page = 0, orderBy } = args;
 		if (!resourceId || typeof resourceId !== "string" || resourceId.trim().length === 0) throw new _mastra_core_error.MastraError({
-			id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES", "INVALID_QUERY"),
+			id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES_BY_RESOURCE_ID", "INVALID_QUERY"),
 			domain: _mastra_core_error.ErrorDomain.STORAGE,
 			category: _mastra_core_error.ErrorCategory.USER,
 			details: { resourceId: resourceId ?? "" }
 		}, /* @__PURE__ */ new Error("resourceId is required"));
 		if (page < 0) throw new _mastra_core_error.MastraError({
-			id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES", "INVALID_PAGE"),
+			id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES_BY_RESOURCE_ID", "INVALID_PAGE"),
 			domain: _mastra_core_error.ErrorDomain.STORAGE,
 			category: _mastra_core_error.ErrorCategory.USER,
 			details: { page }
@@ -6994,21 +7033,16 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 				hasMore: perPageInput !== false && offset + perPage < total
 			};
 		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError && error.category === _mastra_core_error.ErrorCategory.USER) throw error;
 			const mastraError = new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES", "FAILED"),
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_MESSAGES_BY_RESOURCE_ID", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
 				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
 				details: { resourceId }
 			}, error);
 			this.logger?.error?.(mastraError.toString());
 			this.logger?.trackException?.(mastraError);
-			return {
-				messages: [],
-				total: 0,
-				page,
-				perPage: perPageForResponse,
-				hasMore: false
-			};
+			throw mastraError;
 		}
 	}
 	async saveMessages({ messages }) {
@@ -7356,13 +7390,7 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 			}, error);
 			this.logger?.trackException?.(mastraError);
 			this.logger?.error?.(mastraError.toString());
-			return {
-				threads: [],
-				total: 0,
-				page,
-				perPage: perPageForResponse,
-				hasMore: false
-			};
+			throw mastraError;
 		}
 	}
 	async saveThread({ thread }) {