@mastra/libsql 1.0.0-beta.12 → 1.0.0-beta.14

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # @mastra/libsql
 
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- Fixed duplicate spans migration issue across all storage backends. When upgrading from older versions, existing duplicate (traceId, spanId) combinations in the spans table could prevent the unique constraint from being created. The migration deduplicates spans before adding the constraint. ([#12073](https://github.com/mastra-ai/mastra/pull/12073))
+
+  **Deduplication rules (in priority order):**
+  1. Keep completed spans (those with `endedAt` set) over incomplete spans
+  2. Among spans with the same completion status, keep the one with the newest `updatedAt`
+  3. Use `createdAt` as the final tiebreaker
+
+  **What changed:**
+  - Added `migrateSpans()` method to observability stores for manual migration
+  - Added `checkSpansMigrationStatus()` method to check if migration is needed
+  - All stores use optimized single-query deduplication to avoid memory issues on large tables
+
+  **Usage example:**
+
+  ```typescript
+  const observability = await storage.getStore('observability');
+  const status = await observability.checkSpansMigrationStatus();
+  if (status.needsMigration) {
+    const result = await observability.migrateSpans();
+    console.log(`Migration complete: ${result.duplicatesRemoved} duplicates removed`);
+  }
+  ```
+
+  Fixes #11840
+
+- Renamed MastraStorage to MastraCompositeStore for better clarity. The old MastraStorage name remains available as a deprecated alias for backward compatibility, but will be removed in a future version. ([#12093](https://github.com/mastra-ai/mastra/pull/12093))
+
+  **Migration:**
+
+  Update your imports and usage:
+
+  ```typescript
+  // Before
+  import { MastraStorage } from '@mastra/core/storage';
+
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: { ... }
+  });
+
+  // After
+  import { MastraCompositeStore } from '@mastra/core/storage';
+
+  const storage = new MastraCompositeStore({
+    id: 'composite',
+    domains: { ... }
+  });
+  ```
+
+  The new name better reflects that this is a composite storage implementation that routes different domains (workflows, traces, messages) to different underlying stores, avoiding confusion with the general "Mastra Storage" concept.
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+
+## 1.0.0-beta.13
+
+### Patch Changes
+
+- Added new `listThreads` method for flexible thread filtering across all storage adapters. ([#11832](https://github.com/mastra-ai/mastra/pull/11832))
+
+  **New Features**
+  - Filter threads by `resourceId`, `metadata`, or both (with AND logic for metadata key-value pairs)
+  - All filter parameters are optional, allowing you to list all threads or filter as needed
+  - Full pagination and sorting support
+
+  **Example Usage**
+
+  ```typescript
+  // List all threads
+  const allThreads = await memory.listThreads({});
+
+  // Filter by resourceId only
+  const userThreads = await memory.listThreads({
+    filter: { resourceId: 'user-123' },
+  });
+
+  // Filter by metadata only
+  const supportThreads = await memory.listThreads({
+    filter: { metadata: { category: 'support' } },
+  });
+
+  // Filter by both with pagination
+  const filteredThreads = await memory.listThreads({
+    filter: {
+      resourceId: 'user-123',
+      metadata: { priority: 'high', status: 'open' },
+    },
+    orderBy: { field: 'updatedAt', direction: 'DESC' },
+    page: 0,
+    perPage: 20,
+  });
+  ```
+
+  **Security Improvements**
+  - Added validation to prevent SQL injection via malicious metadata keys
+  - Added pagination parameter validation to prevent integer overflow attacks
+
+- Updated dependencies [[`ed3e3dd`](https://github.com/mastra-ai/mastra/commit/ed3e3ddec69d564fe2b125e083437f76331f1283), [`6833c69`](https://github.com/mastra-ai/mastra/commit/6833c69607418d257750bbcdd84638993d343539), [`47b1c16`](https://github.com/mastra-ai/mastra/commit/47b1c16a01c7ffb6765fe1e499b49092f8b7eba3), [`3a76a80`](https://github.com/mastra-ai/mastra/commit/3a76a80284cb71a0faa975abb3d4b2a9631e60cd), [`8538a0d`](https://github.com/mastra-ai/mastra/commit/8538a0d232619bf55dad7ddc2a8b0ca77c679a87), [`9312dcd`](https://github.com/mastra-ai/mastra/commit/9312dcd1c6f5b321929e7d382e763d95fdc030f5)]:
+  - @mastra/core@1.0.0-beta.25
+
 ## 1.0.0-beta.12
 
 ### Minor Changes

package/dist/docs/README.md

@@ -36,4 +36,4 @@ docs/
 ## Version
 
 Package: @mastra/libsql
-Version: 1.0.0-beta.12
+Version: 1.0.0-beta.14

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/libsql. Includes links to type definition
 
 # @mastra/libsql Documentation
 
-> **Version**: 1.0.0-beta.12
+> **Version**: 1.0.0-beta.14
 > **Package**: @mastra/libsql
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/agents/01-agent-memory.md

@@ -90,6 +90,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
 ## Message history
 
 Include a `memory` object with both `resource` and `thread` to track message history during agent calls.
@@ -122,6 +125,9 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 });
 ```
 
+> **Note:**
+Each thread has an owner (`resourceId`) that cannot be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
 To learn more about memory see the [Memory](../memory/overview) documentation.
 
 ## Using `RequestContext`

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

@@ -64,6 +64,67 @@ const handleDecline = async () => {
 };
 ```
 
+## Tool approval with generate()
+
+Tool approval also works with the `generate()` method for non-streaming use cases. When using `generate()` with `requireToolApproval: true`, the method returns immediately when a tool requires approval instead of executing it.
+
+### How it works
+
+When a tool requires approval during a `generate()` call, the response includes:
+
+- `finishReason: 'suspended'` - indicates the agent is waiting for approval
+- `suspendPayload` - contains tool call details (`toolCallId`, `toolName`, `args`)
+- `runId` - needed to approve or decline the tool call
+
+### Approving tool calls
+
+To approve a tool call with `generate()`, use the `approveToolCallGenerate` method:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  console.log("Tool requires approval:", output.suspendPayload.toolName);
+  console.log("Arguments:", output.suspendPayload.args);
+
+  // Approve the tool call and get the final result
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log("Final result:", result.text);
+}
+```
+
+### Declining tool calls
+
+To decline a tool call, use the `declineToolCallGenerate` method:
+
+```typescript
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  // Agent will respond acknowledging the declined tool
+  console.log(result.text);
+}
+```
+
+### Stream vs Generate comparison
+
+| Aspect | `stream()` | `generate()` |
+|--------|-----------|--------------|
+| Response type | Streaming chunks | Complete response |
+| Approval detection | `tool-call-approval` chunk | `finishReason: 'suspended'` |
+| Approve method | `approveToolCall({ runId })` | `approveToolCallGenerate({ runId, toolCallId })` |
+| Decline method | `declineToolCall({ runId })` | `declineToolCallGenerate({ runId, toolCallId })` |
+| Result | Stream to iterate | Full output object |
+
 ## Tool-level approval
 
 There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.

package/dist/docs/memory/02-storage.md

@@ -63,17 +63,17 @@ This is useful when all primitives share the same storage backend and have simil
 
 #### Composite storage
 
-Add storage to your Mastra instance using `MastraStorage` and configure individual storage domains to use different storage providers.
+Add storage to your Mastra instance using `MastraCompositeStore` and configure individual storage domains to use different storage providers.
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { WorkflowsPG } from "@mastra/pg";
 import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     domains: {
       memory: new MemoryLibSQL({ url: "file:./memory.db" }),
@@ -115,6 +115,9 @@ export const agent = new Agent({
 
 This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
 
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
 ## Threads and resources
 
 Mastra organizes memory into threads using two identifiers:
@@ -136,6 +139,21 @@ const stream = await agent.stream("message for agent", {
 > **Note:**
 [Studio](https://mastra.ai/docs/v1/getting-started/studio) automatically generates a thread and resource ID for you. Remember to  to pass these explicitly when calling `stream` or `generate` yourself.
 
+### Thread and resource relationship
+
+Each thread has an owner (its `resourceId`) that is set when the thread is created and cannot be changed. When you query a thread, you must use the correct owner's resource ID. Attempting to query a thread with a different resource ID will result in an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+Note that while each thread has one owner, messages within that thread can have different `resourceId` values. This is used for message attribution and filtering (e.g., distinguishing between different agents in a multi-agent system, or filtering messages for analytics).
+
+**Security:** Memory is a storage layer, not an authorization layer. Your application must implement access control before calling memory APIs. The `resourceId` parameter controls both validation and filtering - provide it to validate ownership and filter messages, or omit it for server-side access without validation.
+
+To avoid accidentally reusing thread IDs across different owners, use UUIDs: `crypto.randomUUID()`
+
 ### Thread title generation
 
 Mastra can automatically generate descriptive thread titles based on the user's first message.

package/dist/docs/memory/06-reference.md

@@ -127,7 +127,7 @@ export const agent = new Agent({
 - [createThread](https://mastra.ai/reference/v1/memory/createThread)
 - [recall](https://mastra.ai/reference/v1/memory/recall)
 - [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/v1/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
 - [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)

package/dist/docs/storage/01-reference.md

@@ -9,11 +9,11 @@
 
 > Documentation for combining multiple storage backends in Mastra.
 
-`MastraStorage` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+`MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
 
 ## Installation
 
-`MastraStorage` is included in `@mastra/core`:
+`MastraCompositeStore` is included in `@mastra/core`:
 
 ```bash
 npm install @mastra/core@beta
@@ -44,13 +44,13 @@ Mastra organizes storage into five specialized domains, each handling a specific
 Import domain classes directly from each store package and compose them:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     domains: {
       memory: new MemoryLibSQL({ url: "file:./local.db" }),
@@ -66,7 +66,7 @@ export const mastra = new Mastra({
 Use `default` to specify a fallback storage, then override specific domains:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { PostgresStore } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
@@ -77,7 +77,7 @@ const pgStore = new PostgresStore({
 });
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     default: pgStore,
     domains: {
@@ -91,14 +91,14 @@ export const mastra = new Mastra({
 
 ## Initialization
 
-`MastraStorage` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+`MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { Mastra } from "@mastra/core";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
@@ -115,10 +115,10 @@ export const mastra = new Mastra({
 If using storage directly, call `init()` explicitly:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG } from "@mastra/pg";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
@@ -139,11 +139,11 @@ const thread = await memoryStore?.getThreadById({ threadId: "..." });
 Use a local database for development while keeping production data in a managed service:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     // Use local SQLite for development, PostgreSQL for production
@@ -162,11 +162,11 @@ const storage = new MastraStorage({
 Use a time-series database for traces while keeping other data in PostgreSQL:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),