@mastra/libsql 1.23.1-alpha.0 → 1.23.1-alpha.2

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.23.1-alpha.0"
+  version: "1.23.1-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-memory-message-history.md

@@ -170,6 +170,43 @@ export const supportAgent = new Agent({
 
 Title generation runs asynchronously after the agent responds and doesn't affect response time.
 
+### Streaming the generated title
+
+By default title generation runs in the background and the run's stream doesn't wait for it, so HTTP clients only see the title on their next thread fetch. Set `emitEvent: true` to deliver the title on the run's stream instead: the stream waits for the title and emits a transient `data-thread-title` chunk before `finish`.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        emitEvent: true,
+      },
+    },
+  }),
+})
+```
+
+Stream consumers receive the chunk with the persisted title, so a chat UI can rename its thread list entry without polling:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-thread-title') {
+    renameThreadInSidebar(chunk.data.threadId, chunk.data.title)
+  }
+}
+```
+
+The chunk is transient: it's delivered to stream consumers but never persisted as part of the conversation's messages. Because the stream waits for the title, `emitEvent` delays the stream's `finish` on the turn that generates the title: the first turn of a thread, or a later turn when `minMessages` sets a higher threshold. Leave it off to keep title generation fully non-blocking.
+
+> **Note:** `emitEvent` applies to `stream()` runs. `generate()` returns JSON and can't carry the chunk, so it keeps non-blocking title generation. [Durable and evented agents](https://mastra.ai/docs/harness/durable-agents) don't emit this chunk yet. In all of these cases the title is still generated and persisted.
+
 To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
 ```typescript

package/dist/docs/references/integrations-channels-github.md

@@ -41,9 +41,13 @@ GitHub Signals requires:
 - A Mastra storage adapter with memory and notification support. The provider stores each subscription in the thread's metadata, so the thread must already exist.
 - The `gitcrawl` command on `PATH`, configured to access the repositories you want to monitor. The provider runs `gitcrawl sync` and reads its SQLite database.
 - The `sqlite3` command on `PATH`.
-- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses `gh api` to check whether comment authors have access to the repository before notifying the agent.
+- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses real `gh api` responses to check repository permissions and GitHub App ownership before notifying the agent.
 
-By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are also allowed. Configure `authorizedPermissions`, `authorizedBots`, or `ignoredBots` when you need different rules.
+By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are explicitly allowed.
+
+Bot authorization checks `ignoredBots` first, using an exact case-insensitive login match. Other bots can trigger notifications when they appear in `authorizedBots`, when the GitHub App is owned by a user whose repository permission appears in `authorizedPermissions`, or when the app is owned by the organization that owns the repository. The default authorized permissions are `admin`, `maintain`, and `write`.
+
+Failed, inaccessible, malformed, and unsupported app-owner lookups deny the bot comment. Successful app-owner lookups are cached for 24 hours; failed lookups aren't cached.
 
 ## Agent and subscription
 

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

@@ -51,7 +51,7 @@ export const agent = new Agent({
 
 **options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
 
-**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
+**options.generateTitle** (`boolean | { model?: DynamicArgument<MastraModelConfig>; instructions?: DynamicArgument<string>; minMessages?: number; emitEvent?: boolean }`): Controls automatic thread title generation from the conversation transcript. Accepts a boolean or an object with a custom model (any MastraModelConfig: a model instance, a "provider/model" ID, or an OpenAI-compatible config; defaults to the agent's own model), custom instructions, a minimum message count, and emitEvent. With emitEvent: true the run's stream waits for the title and emits it as a transient data-thread-title chunk before finish (durable and evented agents persist the title but don't emit the chunk yet).
 
 ## Returns
 

package/dist/docs/references/reference-storage-retention.md

@@ -6,11 +6,37 @@
 
 Because storage grows without bound by default, Mastra provides an opt-in, age-based retention system. Declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Unconfigured data is kept forever, so behavior doesn't change until you opt in.
 
-`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+`prune()` deletes rows in bounded batches. Runs are resumable and cancellable, so you can limit how much work each maintenance window performs. Pruning doesn't reclaim disk space by itself. Use the database-specific maintenance guidance below when you need to return freed space to the operating system.
 
 Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
-The reference implementations are [libSQL](https://mastra.ai/integrations/databases/libsql), [PostgreSQL](https://mastra.ai/integrations/databases/postgresql), and [MongoDB](https://mastra.ai/integrations/databases/mongodb). Other adapters keep rows forever until they implement retention.
+Storage adapters use the shared core retention contract for `prune()`, or a database-native mechanism when that better matches the backend.
+
+| Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
+| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
+| PostgreSQL           | `prune()`               | All supported growth domains. V-next observability drops expired partitions or chunks                                                                                                  |
+| MongoDB              | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
+| DuckDB               | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
+| MySQL                | `prune()`               | Observability spans                                                                                                                                                                    |
+| Microsoft SQL Server | `prune()`               | Observability spans                                                                                                                                                                    |
+| Oracle Database      | `prune()`               | Observability spans and logs                                                                                                                                                           |
+| Amazon Aurora DSQL   | `prune()`               | Observability spans                                                                                                                                                                    |
+| Google Cloud Spanner | `prune()`               | Observability spans, plus metrics when metrics storage is enabled                                                                                                                      |
+| ClickHouse           | Native TTL              | Observability spans, metrics, logs, scores, and feedback. When all five signals have finite retention, deletion-request records expire after the longest signal retention plus 30 days |
+
+## Storage-specific maintenance
+
+| Adapter           | Maintenance guidance                                                                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite and libSQL | Freed pages are reused by future writes, which stops the database file from growing. Reclaiming disk space requires database-level maintenance. |
+| DuckDB            | For file-backed stores, run `CHECKPOINT` after pruning to reclaim deleted rows in storage. DuckDB's `VACUUM` doesn't reclaim deleted rows.      |
+
+## Schedule pruning
+
+Run `prune()` from a scheduler or maintenance worker, not from application startup or shutdown hooks. For deployments that share a database, prefer a single active scheduler or worker for pruning.
+
+Prefer lower-traffic periods when pruning large tables. Use `maxBatches`, `maxRows`, and `pauseMs` to bound each run, and pass an `AbortSignal` when the maintenance process needs to stop promptly. These recommendations apply to adapters that expose `prune()`. ClickHouse applies its native time to live (TTL) policy within the database.
 
 ## Usage example
 
@@ -94,7 +120,8 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
-> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`.
+> - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.
+> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`. DuckDB, MySQL, Microsoft SQL Server, Oracle Database, Amazon Aurora DSQL, and Google Cloud Spanner currently support retention only in their `observability` domains, with the signal coverage shown in the support matrix.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
@@ -109,7 +136,7 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 Pass `options.retention` to replace the configured policies for that call only: for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
 
-Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index.
+Adapters that use anchor-column indexes create them lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index. DuckDB uses its built-in zone maps instead of creating retention indexes.
 
 ```typescript
 const results = await storage.prune({
@@ -177,6 +204,31 @@ async function retentionTick() {
 
 You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
+## ClickHouse native TTL
+
+ClickHouse observability storage uses native table TTLs instead of `prune()`. Configure retention as days per signal. `init()` applies the TTLs to new and existing tables and skips `ALTER TABLE` statements when the configured TTL is already present.
+
+For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the v-next observability store:
+
+```typescript
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const observability = new ObservabilityStorageClickhouseVNext({
+  client,
+  retention: {
+    tracing: 30,
+    logs: 7,
+    metrics: 14,
+    scores: 90,
+    feedback: 60,
+  },
+})
+
+await observability.applyRetention()
+```
+
+Deletion requests are retained long enough to keep enforcing erasure after signal rows expire. Mastra applies a TTL to `mastra_deletion_requests` only when tracing, logs, metrics, scores, and feedback all have finite retention. The deletion-request TTL is the longest of those periods plus 30 days. For example, if score retention is the longest period at 90 days, deletion requests expire after 120 days. When any signal is unbounded, deletion requests remain unbounded because trace deletion requests cover rows across all five signals.
+
 ## MongoDB TTL indexes (alternative to prune)
 
 MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) that automatically delete expired documents without requiring manual `prune()` calls. This is a database-level feature that runs as a background thread.

package/dist/index.cjs

@@ -2873,13 +2873,6 @@ var AgentsLibSQL = class extends _mastra_core_storage.AgentsStorage {
 };
 //#endregion
 //#region src/storage/retention.ts
-const DEFAULT_BATCH_SIZE = 1e3;
-/**
-* Lazily create the single-column anchor index a prune target relies on.
-* Called from the prune path (not init) so only deployments that actually
-* configure retention pay the index's write/disk overhead. Best-effort: a
-* failure is logged and pruning proceeds (correct, just slower).
-*/
 async function ensureAnchorIndex(db, target, logger) {
 	if (!target.indexed) return;
 	try {
@@ -2892,134 +2885,32 @@ async function ensureAnchorIndex(db, target, logger) {
 		logger?.warn?.(`Failed to ensure retention index on ${target.table}(${target.column}):`, error);
 	}
 }
-async function sleep(ms, signal) {
-	if (ms <= 0 || signal?.aborted) return;
-	await new Promise((resolve) => {
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			resolve();
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Runs the bounded, batched, cancellable delete loop for a set of tables in the
-* given order (callers pass children before parents for cascade-safe pruning),
-* and returns one {@link PruneResult} per table.
-*
-* The loop:
-* - deletes in chunks of `batchSize` (default 1000), each its own statement;
-* - stops a table's loop when a batch deletes fewer rows than requested (drained),
-*   or when `maxBatches`/`maxRows` is hit, or the `signal` aborts — the latter
-*   three leave `done: false` so the caller can resume;
-* - pauses `pauseMs` between batches when set, to avoid starving live traffic.
-*
-* `prune()` only deletes rows; it never reclaims disk. Freed pages are reused
-* by future writes so the file stops growing. Handing disk back to the OS is
-* left to the underlying database and the operator to manage.
-*/
-/** Convert a policy's `maxAge` into a cutoff bound matching the anchor's storage type. */
 function cutoffFor(policy, anchorType, now = Date.now()) {
-	const cutoffMs = now - (0, _mastra_core_storage.parseDuration)(policy.maxAge);
+	const cutoffMs = (0, _mastra_core_storage.retentionCutoffMs)(policy, now);
 	return anchorType === "epoch-ms" ? cutoffMs : new Date(cutoffMs).toISOString();
 }
-/**
-* Run the bounded/cancellable batched-delete loop for a single logical target,
-* delegating the actual delete of up to `limit` rows to `deleteBatch`. Returns
-* `{ deleted, done }`; `done: false` means the loop stopped on a bound or the
-* abort signal and eligible rows may remain.
-*/
-async function runBatchedDelete({ deleteBatch, batchSize, options }) {
-	if (!Number.isSafeInteger(batchSize) || batchSize <= 0) throw new Error(`retention batchSize must be a positive integer; received ${batchSize}`);
-	let deleted = 0;
-	let batches = 0;
-	while (true) {
-		if (options?.signal?.aborted) return {
-			deleted,
-			done: false
-		};
-		if (options?.maxBatches !== void 0 && batches >= options.maxBatches) return {
-			deleted,
-			done: false
-		};
-		let limit = batchSize;
-		if (options?.maxRows !== void 0) {
-			const remaining = options.maxRows - deleted;
-			if (remaining <= 0) return {
-				deleted,
-				done: false
-			};
-			limit = Math.min(limit, remaining);
-		}
-		const affected = await deleteBatch(limit);
-		deleted += affected;
-		batches += 1;
-		if (affected < limit) return {
-			deleted,
-			done: true
-		};
-		if (options?.pauseMs) await sleep(options.pauseMs, options.signal);
-	}
-}
-async function runPrune({ db, domain, targets, options, logger }) {
-	const results = [];
-	const now = Date.now();
-	for (const target of targets) {
-		if (options?.signal?.aborted) {
-			results.push({
-				domain,
-				table: target.table,
-				deleted: 0,
-				done: false
-			});
-			continue;
-		}
-		await ensureAnchorIndex(db, target, logger);
-		const cutoff = cutoffFor(target.policy, target.anchorType, now);
-		const { deleted, done } = await runBatchedDelete({
-			deleteBatch: (limit) => db.pruneBatch({
-				tableName: target.table,
-				column: target.column,
-				cutoff,
-				limit
-			}),
-			batchSize: target.policy.batchSize ?? DEFAULT_BATCH_SIZE,
-			options
-		});
-		results.push({
-			domain,
-			table: target.table,
-			deleted,
-			done
-		});
-	}
-	return results;
+const runBatchedDelete = _mastra_core_storage.runRetentionBatches;
+function runPrune({ db, domain, targets, options, logger }) {
+	return (0, _mastra_core_storage.executeRetentionPrune)({
+		domain,
+		targets,
+		options,
+		beforeTarget: (target) => ensureAnchorIndex(db, target, logger),
+		cutoffFor: (target, now) => cutoffFor(target.policy, target.anchorType ?? "timestamp", now),
+		deleteBatch: (target, cutoff, limit) => db.pruneBatch({
+			tableName: target.table,
+			column: target.column,
+			cutoff,
+			limit
+		})
+	});
 }
-/**
-* Resolve a domain's `{ tableKey: policy }` map plus its descriptor into an
-* ordered list of {@link PruneTarget}s. `order` lists table keys children-first
-* so cascade-dependent rows are removed before their parents. Table keys not in
-* `policies` are skipped (unset = keep forever).
-*/
 function resolveTargets({ policies, descriptor, order }) {
-	const targets = [];
-	for (const key of order) {
-		const policy = policies[key];
-		const entry = descriptor[key];
-		if (!policy || !entry) continue;
-		targets.push({
-			table: entry.table,
-			column: entry.column,
-			anchorType: entry.anchorType ?? "timestamp",
-			indexed: entry.indexed ?? true,
-			policy
-		});
-	}
-	return targets;
+	return (0, _mastra_core_storage.resolveRetentionTargets)({
+		policies,
+		descriptor,
+		order
+	});
 }
 //#endregion
 //#region src/storage/domains/background-tasks/index.ts
@@ -13612,7 +13503,7 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 			}
 		}, "deleteWorkflowRunById");
 	}
-	async listWorkflowRuns({ workflowName, fromDate, toDate, page, perPage, resourceId, status } = {}) {
+	async listWorkflowRuns({ workflowName, fromDate, toDate, page, perPage, resourceId, threadId, status } = {}) {
 		try {
 			const conditions = [];
 			const args = [];
@@ -13636,6 +13527,10 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 				conditions.push("resourceId = ?");
 				args.push(resourceId);
 			} else this.logger.warn(`[${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			if (threadId) {
+				conditions.push(`(EXISTS (SELECT 1 FROM json_each(snapshot, '$.context') AS je WHERE json_extract(je.value, '$.status') = 'suspended' AND json_extract(je.value, '$.suspendPayload.__streamState.messageList.memoryInfo.threadId') = ?) OR json_extract(snapshot, '$.context.input.messageListState.memoryInfo.threadId') = ?)`);
+				args.push(threadId, threadId);
+			}
 			const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 			let total = 0;
 			const usePagination = typeof perPage === "number" && typeof page === "number";