@mastra/libsql 1.12.1 → 1.13.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @mastra/libsql
 
+## 1.13.0-alpha.0
+
+### Minor Changes
+
+- Added LibSQL storage support for durable harness sessions. ([#17712](https://github.com/mastra-ai/mastra/pull/17712))
+
+  ```ts
+  const storage = new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' });
+
+  const harness = new Harness({
+    ownerId: 'my-app',
+    agent,
+    memory,
+    storage,
+    modes: [{ id: 'default', defaultModelId: '__GATEWAY_OPENAI_MODEL__' }],
+    defaultModeId: 'default',
+  });
+  ```
+
+- Add `ThreadStateLibSQL`, the LibSQL implementation of the new `ThreadStateStorage` domain. It persists per-thread, per-type state (e.g. the agent task list under `type: "task"`) in the `mastra_thread_state` table, keyed by `(threadId, type)`. Composing a LibSQL store wires this domain automatically, so an agent's task list now survives a process restart. ([#17820](https://github.com/mastra-ai/mastra/pull/17820))
+
+### Patch Changes
+
+- dependencies updates: ([#17148](https://github.com/mastra-ai/mastra/pull/17148))
+  - Updated dependency [`@libsql/client@^0.17.3` ↗︎](https://www.npmjs.com/package/@libsql/client/v/0.17.3) (from `^0.15.15`, in `dependencies`)
+
+- Fixed concurrent writes silently disappearing when using LibSQL with a local (`file:`) database. ([#16796](https://github.com/mastra-ai/mastra/pull/16796))
+
+  LibSQL backs a local database with a single connection. When one operation held an interactive write transaction (for example, persisting workflow snapshots) and another operation wrote at the same time (for example, creating a dataset experiment), the second write could be swept into the open transaction and rolled back — so it appeared to succeed but never persisted. This surfaced as concurrent agent/workflow runs losing unrelated records.
+
+  Writes on a LibSQL client are now serialized, so a write issued during an in-flight transaction no longer interleaves with it.
+
+- Updated dependencies [[`575f815`](https://github.com/mastra-ai/mastra/commit/575f815c5c3567b71c0b83cbb7fa98c8253a9d9c), [`306909a`](https://github.com/mastra-ai/mastra/commit/306909a693de77d709b38706e2673c9547d24a28), [`5191af8`](https://github.com/mastra-ai/mastra/commit/5191af80c799eea25357c545fc05d91b3883531d), [`43bd3d4`](https://github.com/mastra-ai/mastra/commit/43bd3d421987463fdf35386a45199c49499ed069), [`e6fa79e`](https://github.com/mastra-ai/mastra/commit/e6fa79ec72a2ddffdd25e85270398951e9d552a4), [`904bcdf`](https://github.com/mastra-ai/mastra/commit/904bcdf7b8004aa7be823f9f70ca63580e47e470), [`7f5ee1d`](https://github.com/mastra-ai/mastra/commit/7f5ee1dca46daee8d2817f2ebe49e6335da81956), [`1e9aab5`](https://github.com/mastra-ai/mastra/commit/1e9aab50ff11e6e88fde4d7cbf512c44a9fe8d61), [`bf8eb6d`](https://github.com/mastra-ai/mastra/commit/bf8eb6d0ec213a403eb9265a594ad283c44ab3dc), [`493a328`](https://github.com/mastra-ai/mastra/commit/493a328f4346a1deeb9f1e2e44c8f2a3a4d7591b), [`029a414`](https://github.com/mastra-ai/mastra/commit/029a4141719793bd3e898a39eb5a0466a55f5f3a), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`d371ac1`](https://github.com/mastra-ai/mastra/commit/d371ac1d9820afaaf7cfdbc380a475946a994d8f), [`cf182b7`](https://github.com/mastra-ai/mastra/commit/cf182b7fb495767946d9840ef29f19cfa906f31f), [`a049c2a`](https://github.com/mastra-ai/mastra/commit/a049c2a9dfb41d0ee2e7a28874a88cd64fd5669f), [`b147b29`](https://github.com/mastra-ai/mastra/commit/b147b2907f0cd1aa812efe6d6e3f58d22e66fc88), [`2a96528`](https://github.com/mastra-ai/mastra/commit/2a9652848dfa3c5a2426f952e9d93554c26fd90f), [`2656d9c`](https://github.com/mastra-ai/mastra/commit/2656d9c2976d4f3354253bfbbbf9b88a1b2bbf34), [`63e3fe1`](https://github.com/mastra-ai/mastra/commit/63e3fe13cc1ea96f91d7c68aea92f400faf9e4da), [`1d4ce8d`](https://github.com/mastra-ai/mastra/commit/1d4ce8daaa54511f325c1b609d31b8e54009d677), [`8c68372`](https://github.com/mastra-ai/mastra/commit/8c68372e85fe0b066ec12c58bd29ffb93e54c552)]:
+  - @mastra/core@1.42.0-alpha.4
+
 ## 1.12.1
 
 ### Patch 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.12.1"
+  version: "1.13.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-agent-builder-overview.md

@@ -9,6 +9,7 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
 - [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
 - [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
+- [**Tool providers**](https://mastra.ai/docs/agent-builder/integrations): Connect Builder-created agents to third-party apps through OAuth-backed tool providers.
 - [**Skill registries**](https://mastra.ai/docs/agent-builder/skill-registries): Browse and install community skills from opt-in registries.
 - [**Deploying**](https://mastra.ai/docs/agent-builder/deploying): Swap local primitives for cloud-backed storage, filesystems, and sandboxes.
 

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

@@ -96,7 +96,7 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above does not override it. If the function throws, the call requires approval (fail-safe).
+A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above doesn't override it. If the function throws, the call requires approval (fail-safe).
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 
@@ -106,7 +106,7 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
-> **Note:** `suspend()` does not throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+> **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
 

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

@@ -413,12 +413,12 @@ const memory = new Memory({
 What changes:
 
 - **Storage is identical.** The same resource/thread `workingMemory` field is read and written.
-- **The tool is the same shape, exposed under a new name.** Writes still flow through the same underlying tool; on this path it is registered as `setWorkingMemory` (instead of `updateWorkingMemory`). The rename keeps legacy strip filters from removing tool-call parts so they persist as a normal audit trail and the next model step picks the new value up automatically.
+- **The tool is the same shape, exposed under a new name.** Writes still flow through the same underlying tool; on this path it's registered as `setWorkingMemory` (instead of `updateWorkingMemory`). The rename keeps legacy strip filters from removing tool-call parts so they persist as a normal audit trail and the next model step picks the new value up automatically.
 - **Delivery only.** Instead of folding into the system prompt, `Memory` auto-attaches a `WorkingMemoryStateProcessor` that emits the current working memory as a `state` signal with `stateId: 'working-memory'`.
 
 You inherit the standard state-signal benefits: thread-scoped tracking metadata, `cacheKey` dedup so identical snapshots are only emitted once, and `contextWindow.hasSnapshot` re-injection when an older snapshot rolls out of the window.
 
-The default (`useStateSignals: false`) keeps the existing system-message behavior unchanged. `useStateSignals` is not supported with template working memory `version: 'vnext'`.
+The default (`useStateSignals: false`) keeps the existing system-message behavior unchanged. `useStateSignals` isn't supported with template working memory `version: 'vnext'`.
 
 ## Examples
 

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

@@ -27,6 +27,24 @@ export const mastra = new Mastra({
 })
 ```
 
+Enable scheduled notification dispatch when deferred notification records and notification summaries should be delivered automatically through the workflow scheduler:
+
+```typescript
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  storage,
+  notifications: {
+    dispatch: {
+      enabled: true,
+      cron: '*/1 * * * *',
+      batchSize: 100,
+    },
+  },
+})
+```
+
+`notifications.dispatch.enabled` registers an internal workflow with the default cron `*/1 * * * *`. The dispatcher reads due notification records from storage, groups summaries by `agentId`, `resourceId`, and `threadId`, and emits signals through the agent thread runtime. It isn't a user-facing entrypoint.
+
 ## Constructor parameters
 
 Visit the [Configuration reference](https://mastra.ai/reference/configuration) for detailed documentation on all available configuration options.
@@ -67,6 +85,16 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **memory** (`Record<string, MastraMemory>`): Memory instances to register. These can be referenced by stored agents and resolved at runtime. Structured as a key-value pair, with keys being the registry key and values being memory instances. (Default: `{}`)
 
+**notifications** (`object`): Runtime configuration for notification signal dispatch.
+
+**notifications.dispatch** (`NotificationDispatchConfig`): Scheduled dispatch configuration for deferred notifications and notification summaries. Dispatch is enabled by default.
+
+**notifications.dispatch.enabled** (`boolean`): Set to \`false\` to opt out of automatic scheduled notification dispatch.
+
+**notifications.dispatch.cron** (`string`): Cron schedule used by the internal notification dispatcher workflow.
+
+**notifications.dispatch.batchSize** (`number`): Maximum number of due notification records to process per dispatch run.
+
 **versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning) for details.
 
 **versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors. Each selector can target a specific version by ID or by publication status.

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

@@ -240,6 +240,38 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
+> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that haven't migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
-> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for the full list of supported providers.
+### Replicated ClickHouse for multi-replica clusters
+
+For self-managed ClickHouse clusters with multiple replicas, set `replication` so Mastra emits `ReplicatedMergeTree` engines and applies `ON CLUSTER` to its DDL:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { MemoryPG, WorkflowsPG, ScoresPG } from '@mastra/pg'
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const storage = new MastraCompositeStore({
+  id: 'composite',
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    observability: new ObservabilityStorageClickhouseVNext({
+      url: process.env.CLICKHOUSE_URL,
+      username: process.env.CLICKHOUSE_USERNAME,
+      password: process.env.CLICKHOUSE_PASSWORD,
+      replication: {
+        cluster: 'production_cluster',
+        // Optional (defaults shown):
+        // zookeeperPath: '/clickhouse/tables/{shard}/{database}/{table}',
+        // replicaName: '{replica}',
+      },
+    }),
+  },
+})
+```
+
+Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
+
+> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

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

@@ -136,6 +136,6 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 ## Observability
 
-libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for immediate visibility while debugging.
+libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for immediate visibility while debugging.
 
 For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite).