@mastra/pg 1.27.0-alpha.0 → 1.27.0-alpha.1

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.27.0-alpha.0"
+  version: "1.27.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -5666,6 +5666,19 @@ var ChannelsPG = class ChannelsPG extends _mastra_core_storage.ChannelsStorage {
 function jsonbArg(value) {
 	return value === void 0 || value === null ? null : JSON.stringify(value);
 }
+/** Preserve JSON null as data, rather than converting it to an absent SQL value. */
+function jsonDataArg(value) {
+	return value === void 0 ? null : JSON.stringify(value);
+}
+const ITEM_SELECT_COLUMNS = [
+	...Object.keys(_mastra_core_storage.DATASET_ITEMS_SCHEMA),
+	"createdAtZ",
+	"updatedAtZ"
+].map((column) => [
+	"input",
+	"groundTruth",
+	"expectedTrajectory"
+].includes(column) ? `"${column}"::text AS "${column}"` : `"${column}"`).join(", ");
 function parseStoredJSON(value) {
 	if (typeof value === "string") try {
 		return JSON.parse(value);
@@ -5840,9 +5853,9 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 			groundTruthSchema: row.groundTruthSchema ? (0, _mastra_core_storage.safelyParseJSON)(row.groundTruthSchema) : void 0,
 			requestContextSchema: row.requestContextSchema ? (0, _mastra_core_storage.safelyParseJSON)(row.requestContextSchema) : void 0,
 			tags: row.tags ? (0, _mastra_core_storage.safelyParseJSON)(row.tags) : void 0,
-			targetType: row.targetType || null,
-			targetIds: row.targetIds || null,
-			scorerIds: row.scorerIds || null,
+			targetType: row.targetType || void 0,
+			targetIds: row.targetIds ?? void 0,
+			scorerIds: row.scorerIds ?? void 0,
 			organizationId: row.organizationId ?? null,
 			projectId: row.projectId ?? null,
 			candidateKey: row.candidateKey ?? null,
@@ -5944,9 +5957,9 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				inputSchema: input.inputSchema ?? void 0,
 				groundTruthSchema: input.groundTruthSchema ?? void 0,
 				requestContextSchema: input.requestContextSchema ?? void 0,
-				targetType: input.targetType ?? null,
-				targetIds: input.targetIds ?? null,
-				scorerIds: input.scorerIds ?? null,
+				targetType: input.targetType ?? void 0,
+				targetIds: input.targetIds ?? void 0,
+				scorerIds: input.scorerIds ?? void 0,
 				organizationId: input.organizationId ?? null,
 				projectId: input.projectId ?? null,
 				candidateKey: input.candidateKey ?? null,
@@ -6073,9 +6086,9 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				groundTruthSchema: (args.groundTruthSchema !== void 0 ? args.groundTruthSchema : existing.groundTruthSchema) ?? void 0,
 				requestContextSchema: (args.requestContextSchema !== void 0 ? args.requestContextSchema : existing.requestContextSchema) ?? void 0,
 				tags: (args.tags !== void 0 ? args.tags : existing.tags) ?? void 0,
-				targetType: (args.targetType !== void 0 ? args.targetType : existing.targetType) ?? null,
-				targetIds: (args.targetIds !== void 0 ? args.targetIds : existing.targetIds) ?? null,
-				scorerIds: (args.scorerIds !== void 0 ? args.scorerIds : existing.scorerIds) ?? null,
+				targetType: (args.targetType !== void 0 ? args.targetType : existing.targetType) ?? void 0,
+				targetIds: (args.targetIds !== void 0 ? args.targetIds : existing.targetIds) ?? void 0,
+				scorerIds: (args.scorerIds !== void 0 ? args.scorerIds : existing.scorerIds) ?? void 0,
 				organizationId: existing.organizationId ?? null,
 				projectId: existing.projectId ?? null,
 				candidateKey: existing.candidateKey ?? null,
@@ -6253,8 +6266,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 					parentOrganizationId,
 					parentProjectId,
 					JSON.stringify(args.input),
-					jsonbArg(args.groundTruth),
-					jsonbArg(args.expectedTrajectory),
+					jsonDataArg(args.groundTruth),
+					jsonDataArg(args.expectedTrajectory),
 					jsonbArg(args.toolMocks),
 					args.unmockedToolPolicy ?? null,
 					jsonbArg(args.scorerIds),
@@ -6370,8 +6383,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 					parentOrganizationId,
 					parentProjectId,
 					JSON.stringify(mergedInput),
-					jsonbArg(mergedGroundTruth),
-					jsonbArg(mergedExpectedTrajectory),
+					jsonDataArg(mergedGroundTruth),
+					jsonDataArg(mergedExpectedTrajectory),
 					jsonbArg(mergedToolMocks),
 					mergedUnmockedToolPolicy ?? null,
 					jsonbArg(mergedScorerIds),
@@ -6460,8 +6473,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 					parentOrganizationId,
 					parentProjectId,
 					JSON.stringify(existing.input),
-					jsonbArg(existing.groundTruth),
-					jsonbArg(existing.expectedTrajectory),
+					jsonDataArg(existing.groundTruth),
+					jsonDataArg(existing.expectedTrajectory),
 					jsonbArg(existing.toolMocks),
 					existing.unmockedToolPolicy ?? null,
 					jsonbArg(existing.scorerIds),
@@ -6561,7 +6574,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 					details: { datasetId: input.datasetId }
 				});
 				const externalIds = [...new Set(input.items.flatMap((item) => item.externalId ? [item.externalId] : []))];
-				const historyRows = externalIds.length ? await t.manyOrNone(`SELECT * FROM ${itemsTable} WHERE "datasetId" = $1 AND "externalId" = ANY($2::text[]) ORDER BY "datasetVersion"`, [input.datasetId, externalIds]) : [];
+				const historyRows = externalIds.length ? await t.manyOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${itemsTable} WHERE "datasetId" = $1 AND "externalId" = ANY($2::text[]) ORDER BY "datasetVersion"`, [input.datasetId, externalIds]) : [];
 				const plan = this.planDatasetItemBatch(input.items, historyRows.map((row) => this.transformItemRowFull(row)), () => crypto.randomUUID());
 				const resolved = new Map([...plan.existingCurrentItems].map(([id, row]) => [id, this.datasetItemFromRow(row)]));
 				if (plan.inserts.length > 0) {
@@ -6578,8 +6591,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 							dataset.organizationId ?? null,
 							dataset.projectId ?? null,
 							JSON.stringify(item.input),
-							jsonbArg(item.groundTruth),
-							jsonbArg(item.expectedTrajectory),
+							jsonDataArg(item.groundTruth),
+							jsonDataArg(item.expectedTrajectory),
 							jsonbArg(item.toolMocks),
 							item.unmockedToolPolicy ?? null,
 							jsonbArg(item.scorerIds),
@@ -6656,7 +6669,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 					category: _mastra_core_error.ErrorCategory.USER,
 					details: { datasetId: input.datasetId }
 				});
-				const currentItems = (await t.manyOrNone(`SELECT * FROM ${itemsTable} WHERE "id" = ANY($1::text[]) AND "datasetId" = $2 AND "validTo" IS NULL AND "isDeleted" = false`, [input.itemIds, input.datasetId])).map((row) => this.transformItemRow(row));
+				const currentItems = (await t.manyOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${itemsTable} WHERE "id" = ANY($1::text[]) AND "datasetId" = $2 AND "validTo" IS NULL AND "isDeleted" = false`, [input.itemIds, input.datasetId])).map((row) => this.transformItemRow(row));
 				if (currentItems.length === 0) return;
 				const parentOrganizationId = dataset.organizationId ?? null;
 				const parentProjectId = dataset.projectId ?? null;
@@ -6671,8 +6684,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 						parentOrganizationId,
 						parentProjectId,
 						JSON.stringify(item.input),
-						jsonbArg(item.groundTruth),
-						jsonbArg(item.expectedTrajectory),
+						jsonDataArg(item.groundTruth),
+						jsonDataArg(item.expectedTrajectory),
 						jsonbArg(item.toolMocks),
 						item.unmockedToolPolicy ?? null,
 						jsonbArg(item.scorerIds),
@@ -6712,8 +6725,8 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				schemaName: getSchemaName$5(this.#schema)
 			});
 			let result;
-			if (args.datasetVersion !== void 0) result = await client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 AND "datasetVersion" <= $2 AND ("validTo" IS NULL OR "validTo" > $2) AND "isDeleted" = false ORDER BY "datasetVersion" DESC LIMIT 1`, [args.id, args.datasetVersion]);
-			else result = await client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 AND "validTo" IS NULL AND "isDeleted" = false`, [args.id]);
+			if (args.datasetVersion !== void 0) result = await client.oneOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${tableName} WHERE "id" = $1 AND "datasetVersion" <= $2 AND ("validTo" IS NULL OR "validTo" > $2) AND "isDeleted" = false ORDER BY "datasetVersion" DESC LIMIT 1`, [args.id, args.datasetVersion]);
+			else result = await client.oneOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${tableName} WHERE "id" = $1 AND "validTo" IS NULL AND "isDeleted" = false`, [args.id]);
 			return result ? this.transformItemRow(result) : null;
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
@@ -6729,7 +6742,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				indexName: _mastra_core_storage.TABLE_DATASET_ITEMS,
 				schemaName: getSchemaName$5(this.#schema)
 			});
-			return (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} WHERE "datasetId" = $1 AND "datasetVersion" <= $2 AND ("validTo" IS NULL OR "validTo" > $3) AND "isDeleted" = false ORDER BY "createdAt" DESC, "id" ASC`, [
+			return (await this.#db.readClient.manyOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${tableName} WHERE "datasetId" = $1 AND "datasetVersion" <= $2 AND ("validTo" IS NULL OR "validTo" > $3) AND "isDeleted" = false ORDER BY "createdAt" DESC, "id" ASC`, [
 				datasetId,
 				version,
 				version
@@ -6748,7 +6761,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 				indexName: _mastra_core_storage.TABLE_DATASET_ITEMS,
 				schemaName: getSchemaName$5(this.#schema)
 			});
-			return (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1 ORDER BY "datasetVersion" DESC`, [itemId]) || []).map((row) => this.transformItemRowFull(row));
+			return (await this.#db.readClient.manyOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${tableName} WHERE "id" = $1 ORDER BY "datasetVersion" DESC`, [itemId]) || []).map((row) => this.transformItemRowFull(row));
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "GET_ITEM_HISTORY", "FAILED"),
@@ -6820,7 +6833,7 @@ var DatasetsPG = class DatasetsPG extends _mastra_core_storage.DatasetsStorage {
 			const { offset, perPage: perPageForResponse } = (0, _mastra_core_storage.calculatePagination)(page, perPageInput, perPage);
 			const limitValue = perPageInput === false ? total : perPage;
 			return {
-				items: (await client.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
+				items: (await client.manyOrNone(`SELECT ${ITEM_SELECT_COLUMNS} FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
 					...queryParams,
 					limitValue,
 					offset
@@ -17270,7 +17283,8 @@ const TRACE_FIELDS = {
 	entityName: "r.\"entityName\"",
 	entityType: "r.\"entityType\"",
 	environment: "r.\"environment\"",
-	status: TRACE_STATUS_SQL
+	status: TRACE_STATUS_SQL,
+	tags: "r.\"tags\""
 };
 const SPAN_FIELDS = {
 	name: "s.\"name\"",
@@ -17372,6 +17386,19 @@ function compileScalarPredicate(predicate, registry, parameterOffset, allowMetad
 		sql: `${field} IS ${predicate.operator === "exists" ? "NOT " : ""}NULL`,
 		values: fieldValues
 	};
+	if (predicate.type === "collection") {
+		if (predicate.operator === "includes" || predicate.operator === "notIncludes") {
+			const contains = `${field} @> ARRAY[$${parameterOffset}]::text[]`;
+			return {
+				sql: predicate.operator === "includes" ? contains : `cardinality(${field}) > 0 AND NOT (${contains})`,
+				values: [...fieldValues, predicate.value]
+			};
+		}
+		return {
+			sql: `cardinality(${field}) ${predicate.operator === "empty" ? "=" : ">"} 0`,
+			values: fieldValues
+		};
+	}
 	if (predicate.type === "membership") {
 		const list = placeholders(predicate.values, parameterOffset);
 		if (predicate.operator === "in") return {
@@ -17425,6 +17452,7 @@ function compileFeedbackScalarPredicate(predicate, parameterOffset) {
 		};
 	}
 	if (predicate.field !== "value") return compileScalarPredicate(predicate, FEEDBACK_FIELDS, parameterOffset);
+	if (predicate.type === "collection") throw new Error(`Unsupported trusted trace-query field: ${predicate.field}`);
 	if (predicate.type === "presence") {
 		const present = `(s."valueString" IS NOT NULL OR s."valueNumber" IS NOT NULL)`;
 		return {
@@ -17808,22 +17836,23 @@ LIMIT $${values.length}`,
 }
 function compilePostgresTraceQueryValues(schema, plan) {
 	const { ctes, values } = compilePostgresTraceScope(schema, plan, discoveryCollections(plan.predicateScope), plan.scope);
-	let field;
-	if (plan.predicateScope === "trace" && plan.path.startsWith("metadata.")) {
+	let extracted;
+	if (plan.predicateScope === "trace" && plan.path === "tags") extracted = `SELECT value FROM (SELECT DISTINCT r."traceId", UNNEST(r."tags") AS value FROM root_scope r) t`;
+	else if (plan.predicateScope === "trace" && plan.path.startsWith("metadata.")) {
 		const keyParameter = `$${values.length + 1}`;
-		field = `COALESCE(
+		extracted = `SELECT COALESCE(
       CASE WHEN jsonb_typeof(r."metadataSearch" -> ${keyParameter}) = 'string' THEN r."metadataSearch" ->> ${keyParameter} END,
       CASE WHEN jsonb_typeof(r."metadataRaw" -> ${keyParameter}) = 'string' THEN NULLIF(btrim(r."metadataRaw" ->> ${keyParameter}), '') END
-    )`;
+    )::text AS value FROM root_scope r`;
 		values.push(plan.path.slice(9));
-	} else field = fieldSql(discoveryRegistry(plan.predicateScope), plan.path);
+	} else extracted = `SELECT ${fieldSql(discoveryRegistry(plan.predicateScope), plan.path)}::text AS value FROM ${discoverySource(plan.predicateScope)}`;
 	const searchParameter = values.length + 1;
 	const search = plan.search ? `AND strpos(lower(value), lower($${searchParameter})) > 0` : "";
 	if (plan.search) values.push(plan.search);
 	values.push(plan.limit + 1);
 	return {
 		text: `WITH ${ctes.join(",\n")}, extracted AS (
-  SELECT ${field}::text AS value FROM ${discoverySource(plan.predicateScope)}
+  ${extracted}
 )
 SELECT value, count(*)::bigint AS count
 FROM extracted