@mastra/libsql 1.27.1-alpha.0 → 1.27.1

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.27.1-alpha.0"
+  version: "1.27.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -456,8 +456,10 @@ const agent = new Agent({
         indexConfig: {
           type: 'hnsw', // Use HNSW for better performance
           metric: 'dotproduct', // Best for OpenAI embeddings
-          m: 16, // Number of bi-directional links (default: 16)
-          efConstruction: 64, // Size of candidate list during construction (default: 64)
+          hnsw: {
+            m: 16, // Number of bi-directional links (default: 16)
+            efConstruction: 64, // Size of candidate list during construction (default: 64)
+          },
         },
       },
     },

package/dist/docs/references/reference-memory-memory-class.md

@@ -4,7 +4,7 @@
 
 # Memory class
 
-The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and, unless that vector store embeds text itself, an embedder.
 
 ## Usage example
 
@@ -31,11 +31,11 @@ export const agent = new Agent({
 
 ## Constructor parameters
 
-**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to new DefaultStorage({ config: { url: "file:memory.db" } }) if not provided.
+**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Optional: when omitted, an agent uses the storage of the Mastra instance it belongs to. If neither is configured, accessing memory.storage throws Memory requires a storage provider to function.
 
 **vector** (`MastraVector | false`): Vector store for semantic search capabilities. Set to false to disable vector operations.
 
-**embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
+**embedder** (`string | EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder for vector embeddings, as a model-router ID string (for example "openai/text-embedding-3-small"), an EmbeddingModel, or an EmbeddingModelV2. Required when semantic recall is enabled and the vector store doesn't generate embeddings itself (vector.isSelfEmbedding is false).
 
 **embeddingDimension** (`number`): Output dimension of the embedder, as a positive integer. When set, Memory uses it to name the semantic recall index instead of embedding a probe string on first use. It must match the vectors the embedder returns: a mismatch throws a MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH error before any index is created. See Setting the embedding dimension.
 
@@ -49,7 +49,7 @@ export const agent = new Agent({
 
 **options.retainFullInput** (`boolean`): When true, the request input is processed exactly as supplied instead of being filtered against stored history. Use this when you assemble the input yourself and need the message sequence preserved. Stored history is still loaded underneath, and every input message that isn't already stored is saved to the thread, including few-shot examples. Can be set per call on memory.options or agent-wide in the memory constructor options.
 
-**options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}.
+**options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires a vector store, and an embedder unless the vector store embeds text itself (isSelfEmbedding). Default topK is 4, default messageRange is {before: 1, after: 1}.
 
 **options.workingMemory** (`WorkingMemory`): Configuration for working memory feature. Can be { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' } or { enabled: boolean } to disable.
 
@@ -128,8 +128,10 @@ export const agent = new Agent({
         indexConfig: {
           type: 'hnsw', // Use HNSW for better performance
           metric: 'dotproduct', // Optimal for OpenAI embeddings
-          m: 16, // Number of bi-directional links
-          efConstruction: 64, // Construction-time candidate list size
+          hnsw: {
+            m: 16, // Number of bi-directional links
+            efConstruction: 64, // Construction-time candidate list size
+          },
         },
       },
       workingMemory: {

package/dist/index.cjs

@@ -501,7 +501,7 @@ const createNumericOperator = (symbol) => {
 			sql: `CAST(json_extract(metadata, ${jsonPath}) AS NUMERIC) ${symbol} ?`,
 			needsValue: true
 		};
-		else return {
+		return {
 			sql: `CAST(json_extract(metadata, ${jsonPath}) AS TEXT) ${symbol} ?`,
 			needsValue: true
 		};
@@ -528,7 +528,8 @@ function buildElemMatchConditions(value) {
 				sql: sql.replace(pattern, `json_extract(elem.value, '$.${jsonPath}')`),
 				values
 			};
-		} else return {
+		}
+		return {
 			sql: `json_extract(elem.value, '$.${parseJsonPathKey(field)}') = ?`,
 			values: [fieldValue]
 		};
@@ -2059,6 +2060,41 @@ var LibSQLDB = class extends _mastra_core_base.MastraBase {
 		});
 	}
 	/**
+	* Updates multiple records in one write batch, with the same retry behavior as
+	* {@link batchUpdate}. Returns, in input order, whether each update changed a row,
+	* so callers can put extra conditions in `keys` (for example `{ endedAt: null }`).
+	*/
+	async batchUpdateReportingChanges({ tableName, updates }) {
+		return this.executeWriteOperationWithRetry(async () => {
+			const changed = updates.map(() => false);
+			const statements = [];
+			const statementIndexes = [];
+			for (const [index, { keys, data }] of updates.entries()) {
+				const filteredData = await this.filterRecordToKnownColumns(tableName, data);
+				if (Object.keys(filteredData).length === 0) continue;
+				statements.push(prepareUpdateStatement({
+					tableName,
+					updates: filteredData,
+					keys
+				}));
+				statementIndexes.push(index);
+			}
+			if (statements.length === 0) return changed;
+			(await withClientWriteLock(this.client, () => this.client.batch(statements, "write"))).forEach((result, i) => {
+				const index = statementIndexes[i];
+				if (index !== void 0) changed[index] = result.rowsAffected > 0;
+			});
+			return changed;
+		}, `batch update in table ${tableName}`).catch((error) => {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "BATCH_UPDATE_REPORTING_CHANGES", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { tableName }
+			}, error);
+		});
+	}
+	/**
 	* Internal batch delete implementation without retry logic.
 	* Each record can be deleted based on single or composite keys.
 	*/
@@ -2191,7 +2227,7 @@ var LibSQLDB = class extends _mastra_core_base.MastraBase {
 	* @returns The total count of matching records
 	*/
 	async selectTotalCount({ tableName, whereClause }) {
-		const statement = `SELECT COUNT(*) as count FROM ${(0, _mastra_core_utils.parseSqlIdentifier)(tableName, "table name")} ${whereClause ? `${whereClause.sql}` : ""}`;
+		const statement = `SELECT COUNT(*) as count FROM ${(0, _mastra_core_utils.parseSqlIdentifier)(tableName, "table name")} ${whereClause ? whereClause.sql : ""}`;
 		const result = await this.client.execute({
 			sql: statement,
 			args: whereClause?.args ?? []
@@ -12563,24 +12599,27 @@ var ObservabilityLibSQL = class ObservabilityLibSQL extends _mastra_core_storage
 			}, error);
 		}
 	}
-	async batchUpdateSpans(args) {
+	#toSpanUpdates(records) {
 		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return records.map((record) => {
+			const data = { ...record.updates };
+			if (data.endedAt instanceof Date) data.endedAt = data.endedAt.toISOString();
+			if (data.startedAt instanceof Date) data.startedAt = data.startedAt.toISOString();
+			data.updatedAt = now;
+			return {
+				keys: {
+					spanId: record.spanId,
+					traceId: record.traceId
+				},
+				data
+			};
+		});
+	}
+	async batchUpdateSpans(args) {
 		try {
 			return this.#db.batchUpdate({
 				tableName: _mastra_core_storage.TABLE_SPANS,
-				updates: args.records.map((record) => {
-					const data = { ...record.updates };
-					if (data.endedAt instanceof Date) data.endedAt = data.endedAt.toISOString();
-					if (data.startedAt instanceof Date) data.startedAt = data.startedAt.toISOString();
-					data.updatedAt = now;
-					return {
-						keys: {
-							spanId: record.spanId,
-							traceId: record.traceId
-						},
-						data
-					};
-				})
+				updates: this.#toSpanUpdates(args.records)
 			});
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
@@ -12590,6 +12629,30 @@ var ObservabilityLibSQL = class ObservabilityLibSQL extends _mastra_core_storage
 			}, error);
 		}
 	}
+	async batchUpdateUnendedSpans(args) {
+		try {
+			const changed = await this.#db.batchUpdateReportingChanges({
+				tableName: _mastra_core_storage.TABLE_SPANS,
+				updates: this.#toSpanUpdates(args.records).map((update) => ({
+					...update,
+					keys: {
+						...update.keys,
+						endedAt: null
+					}
+				}))
+			});
+			return { updated: args.records.filter((_, index) => changed[index]).map(({ traceId, spanId }) => ({
+				traceId,
+				spanId
+			})) };
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "BATCH_UPDATE_UNENDED_SPANS", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.USER
+			}, error);
+		}
+	}
 	async batchDeleteTraces(args) {
 		this.assertUnscopedBatchDeleteTraces(args);
 		try {
@@ -15278,6 +15341,9 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 	supportsConcurrentUpdates() {
 		return true;
 	}
+	supportsGuardedSnapshotWrites() {
+		return true;
+	}
 	parseWorkflowRun(row) {
 		let parsedSnapshot = row.snapshot;
 		if (typeof parsedSnapshot === "string") try {
@@ -15551,7 +15617,7 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 			}
 		}), "updateWorkflowState");
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence, expectedStatus }) {
 		const now = /* @__PURE__ */ new Date();
 		const createdAtValue = (createdAt ?? now).toISOString();
 		const updatedAtValue = (updatedAt ?? now).toISOString();
@@ -15559,21 +15625,30 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 			workflowName,
 			runId
 		});
+		const expected = expectedStatus === void 0 ? [] : Array.isArray(expectedStatus) ? expectedStatus : [expectedStatus];
+		const guard = expectedStatus === void 0 ? "" : expected.length ? ` WHERE json_extract(${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}.snapshot, '$.status') IN (${expected.map(() => "?").join(", ")})` : " WHERE 0";
 		const check = this.#runFenceCheck(fence, runId, "persistWorkflowSnapshot");
-		await this.executeWithRetry(() => withRunFence(this.#client, check, (writer) => writer.execute({
+		return (await this.executeWithRetry(() => withRunFence(this.#client, check, (writer) => writer.execute({
 			sql: `INSERT INTO ${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT} (workflow_name, run_id, resourceId, snapshot, createdAt, updatedAt)
                 VALUES (?, ?, ?, jsonb(?), ?, ?)
                 ON CONFLICT(workflow_name, run_id)
-                DO UPDATE SET resourceId = COALESCE(excluded.resourceId, ${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}.resourceId), snapshot = excluded.snapshot, updatedAt = excluded.updatedAt`,
+                DO UPDATE SET resourceId = COALESCE(excluded.resourceId, ${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}.resourceId), snapshot = excluded.snapshot, updatedAt = excluded.updatedAt${guard}`,
 			args: [
 				workflowName,
 				runId,
 				resourceId ?? null,
 				safeStringify(snapshot),
 				createdAtValue,
-				updatedAtValue
+				updatedAtValue,
+				...expected
 			]
-		})), "persistWorkflowSnapshot");
+		})), "persistWorkflowSnapshot")).rowsAffected > 0;
+	}
+	async loadWorkflowRunStatus({ workflowName, runId }) {
+		return (await this.#client.execute({
+			sql: `SELECT json_extract(snapshot, '$.status') AS status FROM ${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT} WHERE workflow_name = ? AND run_id = ?`,
+			args: [workflowName, runId]
+		})).rows?.[0]?.status ?? null;
 	}
 	async loadWorkflowSnapshot({ workflowName, runId }) {
 		this.logger.debug("Loading workflow snapshot", {