@mastra/libsql 1.23.1-alpha.3 → 1.23.2-alpha.0

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

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -116,7 +116,44 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting takes precedence over the function above. Its rule decides whether that tool needs approval. If the function throws, the call requires approval as a fail-safe.
+The function can be asynchronous. For decisions that depend on the tool name and arguments, use a [classifier](https://mastra.ai/reference/classifier/classifier) to estimate whether the call needs human review:
+
+```typescript
+import { Classifier } from '@mastra/core/classifier'
+import { model } from '../models/evaluation-model'
+import { agent } from './agent'
+
+const approvalClassifier = new Classifier({
+  id: 'tool-approval-classifier',
+  model,
+  questions: {
+    requiresApproval: {
+      type: 'boolean',
+      instructions:
+        'Does this tool call need human approval because it is destructive, irreversible, expensive, or handles sensitive data?',
+    },
+  },
+})
+
+const stream = await agent.stream('Clean up old records', {
+  requireToolApproval: async ({ toolName, args }) => {
+    const result = await approvalClassifier.evaluate({
+      state: {
+        toolName,
+        argumentNames: Object.keys(args),
+      },
+    })
+
+    return result.answers.requiresApproval.probability >= 0.7
+  },
+})
+```
+
+The example sends argument names rather than values because the classifier forwards its state to the configured evaluation model. If the decision requires argument values, redact sensitive data first or use an evaluation model and provider that meet the protected tool's data-handling requirements.
+
+Returning `true` pauses the tool call for human approval. It doesn't approve or decline the call automatically. Choose a threshold that matches the risk of the tools available to the agent. If this `requireToolApproval` function throws, it defaults to requiring approval.
+
+The runtime then combines that result with the tool's `requireApproval` setting. A boolean `true` requires approval, while `false` doesn't disable approval required by `requireToolApproval`. A tool-level `requireApproval` function is authoritative and replaces the combined result for that tool.
 
 > **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.
 

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

@@ -14,6 +14,12 @@ Memory processors are [processors](https://mastra.ai/docs/agents/processors) tha
 
 Mastra automatically adds these processors when memory is enabled:
 
+### `MemoryInputFilter`
+
+Trims client-echoed history before memory loaders run. For an existing thread, it keeps only the current user turn or new tool results. For an empty thread, it keeps the full initial input and removes provider item metadata from assistant parts that could refer to items that don't exist in storage.
+
+This processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
+
 ### `MessageHistory`
 
 Retrieves message history and persists new messages.
@@ -206,7 +212,7 @@ Understanding the execution order is important when combining guardrails with me
 [Memory Processors] → [Your inputProcessors]
 ```
 
-1. **Memory processors run FIRST**: `WorkingMemory`, `MessageHistory`, `SemanticRecall`
+1. **Memory processors run FIRST**: `MemoryInputFilter`, then `WorkingMemory`, `MessageHistory`, and `SemanticRecall`
 2. **Your input processors run AFTER**: guardrails, filters, validators
 
 As a result, memory loads message history before your processors can validate or filter the input.

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

@@ -12,7 +12,9 @@ You can also retrieve message history to display past conversations in your UI.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
-> Sending the full history is redundant because Mastra loads messages from storage, and it can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+> Sending the full history is redundant because Mastra loads messages from storage. Mastra filters client-echoed history before loading stored messages and uses the stored copy as the base when message IDs match, preserving stored timestamps and provider metadata while retaining new tool results.
+>
+> If you assemble the request input yourself and need it processed exactly as sent, set `retainFullInput: true` on `memory.options` for that call, or in the memory constructor options to apply it agent-wide. This disables the filtering described above. History still loads underneath. Every input message that isn't already stored is saved to the thread, including few-shot examples.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui).
 

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

@@ -85,6 +85,8 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **scorers** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs. Registration also makes a scorer resolvable by ID, which is required to persist its scores. See Score persistence (Default: `{}`)
 
+**classifiers** (`Record<string, Classifier>`): Classifiers for typed fixed-option evaluation. Registered classifiers can be retrieved by key or ID. See Classifier (Default: `{}`)
+
 **processors** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
 
 **gateways** (`Record<string, MastraModelGateway>`): Custom model gateways to register for accessing AI models through alternative providers or private deployments. Structured as a key-value pair, with keys being the registry key (used for getGateway()) and values being gateway instances. (Default: `{}`)

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

@@ -45,6 +45,8 @@ export const agent = new Agent({
 
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 
+**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.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.

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

@@ -15,7 +15,7 @@ Storage adapters use the shared core retention contract for `prune()`, or a data
 | Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
 | -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
-| PostgreSQL           | `prune()`               | All supported growth domains. V-next observability drops expired partitions or chunks                                                                                                  |
+| PostgreSQL           | `prune()`               | All supported growth domains. vNext 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                                                                                                                                                                    |
@@ -102,10 +102,10 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 | `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
 | `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
 | `observability`   | `spans`            | `startedAt`      | Span age                                                         |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                   |
-| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                      |
-| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                    |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                 |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                  |
 | `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
 | `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
 | `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
@@ -122,7 +122,7 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - 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.
+> - The vNext 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
 
@@ -208,7 +208,9 @@ You can also cancel a long-running prune with an `AbortSignal`: the loop stops b
 
 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:
+Omitted signals, and signals set to zero or less, get no TTL. When you remove a signal from `retention`, the next `init()` or `applyRetention()` removes that table's TTL. If Mastra can't read the current TTLs from `system.tables`, it applies the configured TTLs and leaves the others unchanged.
+
+For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the vNext observability store:
 
 ```typescript
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'

package/dist/index.cjs

@@ -3503,6 +3503,10 @@ function buildScopedWhere(idColumn, idValue, filters) {
 function jsonbArg(value) {
 	return value === void 0 || value === null ? null : JSON.stringify(value);
 }
+/** Arbitrary JSON fields distinguish authored JSON null from an absent SQL value. */
+function jsonDataArg(value) {
+	return value === void 0 ? null : JSON.stringify(value);
+}
 var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 	#db;
 	#client;
@@ -3608,7 +3612,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 		return {
 			id: row.id,
 			name: row.name,
-			description: row.description,
+			description: row.description ?? void 0,
 			metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : void 0,
 			inputSchema: row.inputSchema ? (0, _mastra_core_storage.safelyParseJSON)(row.inputSchema) : void 0,
 			groundTruthSchema: row.groundTruthSchema ? (0, _mastra_core_storage.safelyParseJSON)(row.groundTruthSchema) : void 0,
@@ -3996,9 +4000,9 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 						args.externalId ?? null,
 						args.datasetId,
 						args.datasetId,
-						jsonbArg(args.input),
-						jsonbArg(args.groundTruth),
-						jsonbArg(args.expectedTrajectory),
+						jsonDataArg(args.input),
+						jsonDataArg(args.groundTruth),
+						jsonDataArg(args.expectedTrajectory),
 						jsonbArg(args.toolMocks),
 						args.unmockedToolPolicy ?? null,
 						jsonbArg(args.scorerIds),
@@ -4120,9 +4124,9 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 							existing.externalId ?? null,
 							organizationId,
 							projectId,
-							jsonbArg(mergedInput),
-							jsonbArg(mergedGroundTruth),
-							jsonbArg(mergedExpectedTrajectory),
+							jsonDataArg(mergedInput),
+							jsonDataArg(mergedGroundTruth),
+							jsonDataArg(mergedExpectedTrajectory),
 							jsonbArg(mergedToolMocks),
 							mergedUnmockedToolPolicy ?? null,
 							jsonbArg(mergedScorerIds),
@@ -4219,9 +4223,9 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 							existing.externalId ?? null,
 							dataset.organizationId ?? null,
 							dataset.projectId ?? null,
-							jsonbArg(existing.input),
-							jsonbArg(existing.groundTruth),
-							jsonbArg(existing.expectedTrajectory),
+							jsonDataArg(existing.input),
+							jsonDataArg(existing.groundTruth),
+							jsonDataArg(existing.expectedTrajectory),
 							jsonbArg(existing.toolMocks),
 							existing.unmockedToolPolicy ?? null,
 							jsonbArg(existing.scorerIds),
@@ -4609,9 +4613,9 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 									item.externalId ?? null,
 									dataset.organizationId ?? null,
 									dataset.projectId ?? null,
-									jsonbArg(item.input),
-									jsonbArg(item.groundTruth),
-									jsonbArg(item.expectedTrajectory),
+									jsonDataArg(item.input),
+									jsonDataArg(item.groundTruth),
+									jsonDataArg(item.expectedTrajectory),
 									jsonbArg(item.toolMocks),
 									item.unmockedToolPolicy ?? null,
 									jsonbArg(item.scorerIds),
@@ -4716,9 +4720,9 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
 								item.externalId ?? null,
 								dataset.organizationId ?? null,
 								dataset.projectId ?? null,
-								jsonbArg(item.input),
-								jsonbArg(item.groundTruth),
-								jsonbArg(item.expectedTrajectory),
+								jsonDataArg(item.input),
+								jsonDataArg(item.groundTruth),
+								jsonDataArg(item.expectedTrajectory),
 								jsonbArg(item.toolMocks),
 								item.unmockedToolPolicy ?? null,
 								jsonbArg(item.scorerIds),