@mastra/libsql 1.27.0-alpha.1 → 1.27.0-alpha.3

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.0-alpha.1"
+  version: "1.27.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-agents-human-in-the-loop.md

@@ -144,7 +144,8 @@ const stream = await agent.stream('Clean up old records', {
       },
     })
 
-    return result.answers.requiresApproval.probability >= 0.7
+    // A refused question has no probability, so it falls back to requiring approval.
+    return (result.answers.requiresApproval.probability ?? 1) >= 0.7
   },
 })
 ```

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

@@ -403,6 +403,8 @@ Memory uses a single embedder for both storing and recalling messages, so pick o
 
 Multilingual E5 produces 1024-dimensional vectors. Your vector index must be created with matching dimensions, and E5 vectors can't be mixed with vectors from another embedder in the same index.
 
+FastEmbed models embed at most 512 tokens per input (roughly 2,000 to 2,500 characters of English text). Longer inputs are truncated, so text past the limit doesn't affect the embedding and can't be found by semantic recall. The AI SDK v3 FastEmbed models return a warning when this happens. The legacy v1 and v2 models don't. If you embed long documents with FastEmbed, chunk them to fit the window, for example with `maxSize: 1500` in `MDocument.chunk()`.
+
 ## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.

package/dist/docs/references/reference-core-mastra-class.md

@@ -147,6 +147,12 @@ Re-drives every orphaned `running` durable-agent run across all registered durab
 
 Requires persistent storage. With an in-memory store, there's nothing to recover after a process restart.
 
+Agents and their runs are attempted serially. Each built-in `recoverActiveRuns()` attempt waits up to 30 seconds in total for `recover()` setup and settlement of the whole recovered workflow, then traversal can continue to later runs and agents. This isn't an overall recovery deadline: discovery and overridden custom recovery methods aren't bounded by this budget.
+
+A timed-out attempt continues in the background. Its outcome is `status: 'skipped'` with `reason: 'recovery-timeout'` and no `retryAt`. It contributes only to `skipped`, not `recovered`, `succeeded`, or `failed`, and Mastra doesn't automatically retry it. Late settlement doesn't change the returned counts.
+
+When shutdown begins, recovery stops dispatching new agents and runs. The recovery traversal and original attempts, including timed-out setup or execution, participate in the same shared shutdown drain as active executions. A recovery wait timeout doesn't cancel the attempt or give it a separate shutdown drain window.
+
 A run that another execution still drives isn't taken over. It's counted in `skipped` and checked again once that execution's claim could have lapsed, so a run whose process crashed is recovered without another call. `shutdown()` cancels pending re-checks. See [run ownership](https://mastra.ai/docs/harness/durable-agents).
 
 ```typescript
@@ -164,4 +170,4 @@ Returns:
 
 **failed** (`number`): Runs whose restart threw an error.
 
-**skipped** (`number`): Runs that another execution still drives. Each is checked again later.
+**skipped** (`number`): Runs skipped because they are already active, recovery is already in progress, or the recovery wait timed out. Only ownership skips eligible for re-checks are checked again; recovery timeouts are not automatically retried.

package/dist/index.cjs

@@ -1645,6 +1645,27 @@ function buildSelectColumnsWithAlias(tableName, alias) {
 function isLockError(error) {
 	return error.code === "SQLITE_BUSY" || error.code === "SQLITE_LOCKED" || error.message?.toLowerCase().includes("database is locked") || error.message?.toLowerCase().includes("database table is locked") || error.message?.toLowerCase().includes("table is locked") || error.constructor.name === "SqliteError" && error.message?.toLowerCase().includes("locked");
 }
+const TRANSIENT_NETWORK_PATTERNS = [
+	"fetch failed",
+	"econnreset",
+	"etimedout",
+	"eai_again",
+	"socket hang up",
+	"und_err_"
+];
+/**
+* Checks if an error (or any error in its `cause` chain) is a transient network failure
+* such as `fetch failed` from a remote libsql client.
+*/
+function isTransientNetworkError(error) {
+	let current = error;
+	for (let depth = 0; current && depth < 5; depth++) {
+		const text = `${current.message ?? ""} ${current.code ?? ""}`.toLowerCase();
+		if (TRANSIENT_NETWORK_PATTERNS.some((pattern) => text.includes(pattern))) return true;
+		current = current.cause;
+	}
+	return false;
+}
 function createExecuteWriteOperationWithRetry({ logger, maxRetries, initialBackoffMs }) {
 	return async function executeWriteOperationWithRetry(operationFn, operationDescription) {
 		let attempts = 0;
@@ -14356,7 +14377,7 @@ var SkillsLibSQL = class extends _mastra_core_storage.SkillsStorage {
 	}
 	async list(args) {
 		try {
-			const { page = 0, perPage: perPageInput, orderBy, authorId, visibility, status, entityIds, pinFavoritedFor, favoritedOnly } = args || {};
+			const { page = 0, perPage: perPageInput, orderBy, authorId, visibility, status, entityIds, pinFavoritedFor, favoritedOnly, metadata } = args || {};
 			const { field, direction } = this.parseOrderBy(orderBy);
 			if (entityIds && entityIds.length === 0) return {
 				skills: [],
@@ -14384,6 +14405,28 @@ var SkillsLibSQL = class extends _mastra_core_storage.SkillsStorage {
 				conditions.push(`s_e.id IN (${placeholders})`);
 				queryParams.push(...entityIds);
 			}
+			if (metadata && Object.keys(metadata).length > 0) {
+				const latestVersionId = `(SELECT lv.id FROM "${_mastra_core_storage.TABLE_SKILL_VERSIONS}" lv WHERE lv."skillId" = s_e.id ORDER BY lv."versionNumber" DESC LIMIT 1)`;
+				const resolvedVersionId = status === "draft" ? latestVersionId : `COALESCE(s_e."activeVersionId", ${latestVersionId})`;
+				const metadataConditions = [];
+				for (const [key, value] of Object.entries(metadata)) {
+					if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) throw new _mastra_core_error.MastraError({
+						id: (0, _mastra_core_storage.createStorageErrorId)("LIBSQL", "LIST_SKILLS", "INVALID_METADATA_KEY"),
+						domain: _mastra_core_error.ErrorDomain.STORAGE,
+						category: _mastra_core_error.ErrorCategory.USER,
+						text: `Invalid metadata key: ${key}. Keys must be alphanumeric with underscores.`,
+						details: { key }
+					});
+					if (typeof value === "string") {
+						metadataConditions.push(`json_extract(mv.metadata, '$.${key}') = ?`);
+						queryParams.push(value);
+					} else {
+						metadataConditions.push(`json_extract(mv.metadata, '$.${key}') = json_extract(?, '$')`);
+						queryParams.push(JSON.stringify(value));
+					}
+				}
+				conditions.push(`EXISTS (SELECT 1 FROM "${_mastra_core_storage.TABLE_SKILL_VERSIONS}" mv WHERE mv."skillId" = s_e.id AND mv.id = ${resolvedVersionId} AND ${metadataConditions.join(" AND ")})`);
+			}
 			const joinUserId = pinFavoritedFor;
 			const useJoin = Boolean(joinUserId);
 			let joinClause = "";
@@ -16584,6 +16627,8 @@ var LibSQLFactoryStorage = class extends _mastra_core_storage.FactoryStorage {
 };
 //#endregion
 //#region src/storage/index.ts
+const REMOTE_INIT_CONCURRENCY = 5;
+const REMOTE_INIT_MAX_ATTEMPTS = 3;
 const DEFAULT_LOCAL_CACHE_SIZE = -16e3;
 const DEFAULT_LOCAL_MMAP_SIZE = 134217728;
 /**
@@ -16730,8 +16775,31 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 		for (const store of this.getStoresToInit()) await store.init();
 		return true;
 	}
+	async initStoreWithRetry(store) {
+		for (let attempt = 1;; attempt++) try {
+			await store.init();
+			return;
+		} catch (error) {
+			if (attempt >= REMOTE_INIT_MAX_ATTEMPTS || !isTransientNetworkError(error)) throw error;
+			const backoff = this.initialBackoffMs * 2 ** (attempt - 1);
+			this.logger.warn(`LibSQLStore: Transient network error during domain init, retrying in ${backoff}ms (attempt ${attempt}/${REMOTE_INIT_MAX_ATTEMPTS}).`, error);
+			await new Promise((resolve) => setTimeout(resolve, backoff));
+		}
+	}
 	async initDomainsInParallel() {
-		await Promise.all(this.getStoresToInit().map((store) => store.init()));
+		const stores = this.getStoresToInit();
+		let next = 0;
+		let failed = false;
+		const worker = async () => {
+			while (!failed && next < stores.length) try {
+				await this.initStoreWithRetry(stores[next++]);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		};
+		const rejected = (await Promise.allSettled(Array.from({ length: Math.min(REMOTE_INIT_CONCURRENCY, stores.length) }, worker))).find((r) => r.status === "rejected");
+		if (rejected) throw rejected.reason;
 		return true;
 	}
 	async init() {
@@ -16742,7 +16810,10 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 					await this.hasInitialized;
 					return;
 				}
-				this.hasInitialized = this.initDomainsInParallel();
+				this.hasInitialized = this.initDomainsInParallel().catch((error) => {
+					this.hasInitialized = null;
+					throw error;
+				});
 				await this.hasInitialized;
 				return;
 			}
@@ -16754,7 +16825,10 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 				await this.hasInitialized;
 				return;
 			}
-			this.hasInitialized = this.initDomainsSequentially();
+			this.hasInitialized = this.initDomainsSequentially().catch((error) => {
+				this.hasInitialized = null;
+				throw error;
+			});
 			await this.hasInitialized;
 			return;
 		}