@mastra/pg 1.26.0-alpha.3 → 1.26.0-alpha.5

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "crypto";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
 import * as coreStorage from "@mastra/core/storage";
-import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_CURSORS_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_CURSORS, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, assertKnowledgeCeilingRaised, assertKnowledgeScopeWithinCeiling, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveRetentionTargets, retentionCutoffMs, runRetentionBatches, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_CURSORS_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_CURSORS, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, assertKnowledgeCeilingRaised, assertKnowledgeScopeWithinCeiling, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, runRetentionBatches, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { parseFieldKey, parseSqlIdentifier } from "@mastra/core/utils";
 import { MastraVector, validateTopK, validateUpsertInput } from "@mastra/core/vector";
 import { Mutex } from "async-mutex";
@@ -2336,6 +2336,8 @@ var RoutingDbClient = class {
 		return this.active.tx(callback);
 	}
 };
+/** Bytes reserved for the `_xxxxxxxx` collision suffix when hashWhenTruncated applies. */
+const TRUNCATION_HASH_SUFFIX_LENGTH = 9;
 function truncateIdentifier(value, maxLength = 63) {
 	if (maxLength <= 0) return "";
 	if (Buffer.byteLength(value, "utf-8") <= maxLength) return value;
@@ -2356,9 +2358,25 @@ function truncateIdentifier(value, maxLength = 63) {
 * in system catalogs (pg_constraint.conname, pg_indexes.indexname, etc.).
 * Without this normalisation, runtime lookups that compare a mixed-case name
 * against the catalog would silently fail.
+*
+* With `hashWhenTruncated`, a name that exceeds the limit is truncated further
+* to make room for `_` + 8 hex chars of the full name's sha256. Plain
+* truncation cuts the tail, so two names sharing a long `<schema>_<prefix>`
+* collapse to the same identifier and `CREATE INDEX IF NOT EXISTS` (which
+* matches by name only) silently skips the second one. The suffix is
+* deterministic, so creation, warm-init snapshot checks, and DDL export all
+* agree on the same name. Opt-in because renaming already-released constraint
+* names would orphan the existing objects in deployed catalogs.
 */
-function buildConstraintName({ baseName, schemaName, maxLength = 63 }) {
-	return truncateIdentifier(`${schemaName ? `${schemaName}_` : ""}${baseName}`.toLowerCase(), maxLength);
+function buildConstraintName({ baseName, schemaName, maxLength = 63, hashWhenTruncated = false }) {
+	const fullName = `${schemaName ? `${schemaName}_` : ""}${baseName}`.toLowerCase();
+	if (hashWhenTruncated && Buffer.byteLength(fullName, "utf-8") > maxLength) {
+		const suffixLength = Math.min(TRUNCATION_HASH_SUFFIX_LENGTH, maxLength);
+		if (suffixLength < 2) return truncateIdentifier(fullName, maxLength);
+		const hash = createHash("sha256").update(fullName).digest("hex").slice(0, suffixLength - 1);
+		return `${truncateIdentifier(fullName, maxLength - suffixLength)}_${hash}`;
+	}
+	return truncateIdentifier(fullName, maxLength);
 }
 //#endregion
 //#region src/storage/db/pg-errors.ts
@@ -6094,6 +6112,14 @@ var DatasetsPG = class DatasetsPG extends DatasetsStorage {
 	}
 	async listDatasets(args) {
 		try {
+			const orderBy = resolveListOrderBy(args.orderBy, [
+				"createdAt",
+				"updatedAt",
+				"name"
+			], {
+				field: "createdAt",
+				direction: "DESC"
+			});
 			const { page, perPage: perPageInput } = args.pagination;
 			const tableName = getTableName$5({
 				indexName: TABLE_DATASETS,
@@ -6149,7 +6175,7 @@ var DatasetsPG = class DatasetsPG extends DatasetsStorage {
 			const { offset, perPage: perPageForResponse } = calculatePagination(page, perPageInput, perPage);
 			const limitValue = perPageInput === false ? total : perPage;
 			return {
-				datasets: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "createdAt" DESC, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
+				datasets: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
 					...queryParams,
 					limitValue,
 					offset
@@ -6716,6 +6742,10 @@ var DatasetsPG = class DatasetsPG extends DatasetsStorage {
 	*/
 	async #listItems(client, args) {
 		try {
+			const orderBy = resolveListOrderBy(args.orderBy, ["createdAt", "updatedAt"], {
+				field: "createdAt",
+				direction: "DESC"
+			});
 			const { page, perPage: perPageInput } = args.pagination;
 			const tableName = getTableName$5({
 				indexName: TABLE_DATASET_ITEMS,
@@ -6766,7 +6796,7 @@ var DatasetsPG = class DatasetsPG extends DatasetsStorage {
 			const { offset, perPage: perPageForResponse } = calculatePagination(page, perPageInput, perPage);
 			const limitValue = perPageInput === false ? total : perPage;
 			return {
-				items: (await client.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "createdAt" DESC, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
+				items: (await client.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
 					...queryParams,
 					limitValue,
 					offset
@@ -7326,6 +7356,10 @@ var ExperimentsPG = class ExperimentsPG extends ExperimentsStorage {
 	}
 	async listExperiments(args) {
 		try {
+			const orderBy = resolveListOrderBy(args.orderBy, ["createdAt", "status"], {
+				field: "createdAt",
+				direction: "DESC"
+			});
 			const { page, perPage: perPageInput } = args.pagination;
 			const tableName = getTableName$5({
 				indexName: TABLE_EXPERIMENTS,
@@ -7397,7 +7431,7 @@ var ExperimentsPG = class ExperimentsPG extends ExperimentsStorage {
 			const { offset, perPage: perPageForResponse } = calculatePagination(page, perPageInput, perPage);
 			const limitValue = perPageInput === false ? total : perPage;
 			return {
-				experiments: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "createdAt" DESC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
+				experiments: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
 					...queryParams,
 					limitValue,
 					offset
@@ -7669,6 +7703,10 @@ var ExperimentsPG = class ExperimentsPG extends ExperimentsStorage {
 	}
 	async listExperimentResults(args) {
 		try {
+			const orderBy = resolveListOrderBy(args.orderBy, ["startedAt", "createdAt"], {
+				field: "startedAt",
+				direction: "ASC"
+			});
 			const { page, perPage: perPageInput } = args.pagination;
 			const tableName = getTableName$5({
 				indexName: TABLE_EXPERIMENT_RESULTS,
@@ -7716,7 +7754,7 @@ var ExperimentsPG = class ExperimentsPG extends ExperimentsStorage {
 			const { offset, perPage: perPageForResponse } = calculatePagination(page, perPageInput, perPage);
 			const limitValue = perPageInput === false ? total : perPage;
 			return {
-				results: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "startedAt" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
+				results: (await this.#db.readClient.manyOrNone(`SELECT * FROM ${tableName} ${whereClause} ORDER BY "${orderBy.field}" ${orderBy.direction}, "id" ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [
 					...queryParams,
 					limitValue,
 					offset
@@ -17255,7 +17293,7 @@ const TRACE_SELECT = `
   r."name" AS "name",
   r."entityId" AS "entityId",
   r."parentSpanId" AS "parentSpanId",
-  r."metadata" AS "metadata",
+  r."metadataRaw" AS "metadata",
   r."input" AS "input",
   r."threadId" AS "threadId",
   r."resourceId" AS "resourceId",
@@ -17473,22 +17511,27 @@ function compileThreadPredicate(predicate, parameterOffset) {
 		values: compiled.values
 	};
 }
-function compilePostgresTraceScope(schema, selection, relationCollections) {
+function compilePostgresTraceScope(schema, selection, relationCollections, deltaWindow) {
 	const spanTable = qualifiedTable(schema, TABLE_SPAN_EVENTS);
 	const scoreTable = qualifiedTable(schema, TABLE_SCORE_EVENTS);
 	const feedbackTable = qualifiedTable(schema, TABLE_FEEDBACK_EVENTS);
 	const values = [selection.timeRange.from, selection.timeRange.to];
-	const ctes = [`root_scope AS MATERIALIZED (
-    SELECT *
-    FROM ${spanTable} r
-    WHERE ${[
+	const rootConditions = [
 		`r."parentSpanId" IS NULL`,
 		latestRootPredicate$1(spanTable),
 		`NOT r."isPending"`,
 		`r."endedAt" IS NOT NULL`,
 		`r."startedAt" >= $1`,
 		`r."startedAt" < $2`
-	].join("\n      AND ")}
+	];
+	if (deltaWindow) {
+		values.push(deltaWindow.xactId, deltaWindow.cursorId, deltaWindow.safeHorizon);
+		rootConditions.push(`(r."xactId", r."cursorId") > ($3::xid8, $4::bigint)`, `r."xactId" < $5::xid8`);
+	}
+	const ctes = [`root_scope AS MATERIALIZED (
+    SELECT *
+    FROM ${spanTable} r
+    WHERE ${rootConditions.join("\n      AND ")}
   )`];
 	if (relationCollections.has("spans")) ctes.push(`current_spans AS MATERIALIZED (
     SELECT
@@ -17557,8 +17600,18 @@ function compilePostgresTraceScope(schema, selection, relationCollections) {
 		values
 	};
 }
-function compilePostgresTraceQuery(schema, plan, mode = "data") {
-	const { ctes, values } = compilePostgresTraceScope(schema, plan, collectRelationCollections(plan.where));
+function compilePostgresTraceQuery(schema, plan, mode = "data", safeHorizon) {
+	const relationCollections = collectRelationCollections(plan.where);
+	let deltaWindow;
+	if (plan.paginationMode === "delta") {
+		const watermark = coreStorage.getTraceQueryDeltaWatermark(plan, "pg");
+		if (watermark === void 0 || safeHorizon === void 0) throw new Error("Delta query requires a cursor and safe horizon");
+		deltaWindow = {
+			...decodeTraceDeltaWatermark(watermark),
+			safeHorizon
+		};
+	}
+	const { ctes, values } = compilePostgresTraceScope(schema, plan, relationCollections, deltaWindow);
 	let predicateSql = "TRUE";
 	if (plan.where) {
 		const predicate = compilePredicate(plan.where, values.length + 1);
@@ -17566,7 +17619,7 @@ function compilePostgresTraceQuery(schema, plan, mode = "data") {
 		values.push(...predicate.values);
 	}
 	ctes.push(`candidates AS (
-    SELECT ${TRACE_SELECT}
+    SELECT ${TRACE_SELECT}${plan.paginationMode === "delta" ? ", r.\"xactId\", r.\"cursorId\"" : ""}
     FROM root_scope r
     WHERE ${predicateSql}
   )`);
@@ -17577,6 +17630,16 @@ SELECT COUNT(*)::text AS count
 FROM candidates`,
 		values
 	};
+	if (plan.paginationMode === "delta") {
+		values.push(plan.limit + 1);
+		return {
+			text: `${candidates}
+SELECT * FROM candidates
+ORDER BY "xactId" ASC, "cursorId" ASC
+LIMIT $${values.length}`,
+			values
+		};
+	}
 	if (plan.result === "groups") {
 		const pageCondition = plan.cursor ? `AND "threadId" > $${values.length + 1}` : "";
 		if (plan.cursor) values.push(plan.cursor.threadId);
@@ -17788,13 +17851,83 @@ async function getTraceQueryValues(client, schema, plan, timeoutMs) {
 		valuesTruncated: rows.length > plan.limit
 	});
 }
+function decodeTraceDeltaWatermark(watermark) {
+	try {
+		return decodeDeltaCursor(watermark);
+	} catch {
+		throw new coreStorage.TraceQueryCursorError("TRACE_QUERY_CURSOR_MALFORMED");
+	}
+}
+function emptyDeltaWatermark(horizon, watermark) {
+	if (watermark !== void 0 && BigInt(decodeTraceDeltaWatermark(watermark).xactId) >= BigInt(horizon)) return watermark;
+	return encodeDeltaCursor(horizon, 0);
+}
+async function setRemainingTimeout(transaction, deadline) {
+	const remainingTimeoutMs = Math.floor(deadline - performance.now());
+	if (remainingTimeoutMs <= 0) throw new coreStorage.TraceQueryExecutionError();
+	await transaction.query(`SELECT set_config('statement_timeout', $1, true)`, [`${remainingTimeoutMs}ms`]);
+}
+function traceRowToResult(row) {
+	return {
+		traceId: String(row.traceId),
+		rootSpanId: String(row.rootSpanId),
+		name: row.name,
+		entityId: row.entityId ?? null,
+		parentSpanId: row.parentSpanId ?? null,
+		createdAt: asIsoTimestamp$1(row.startedAt),
+		metadata: row.metadata ?? null,
+		inputPreview: coreStorage.buildInputPreview(row.input) ?? null,
+		threadId: row.threadId == null ? null : String(row.threadId),
+		resourceId: row.resourceId == null ? null : String(row.resourceId),
+		startedAt: asIsoTimestamp$1(row.startedAt),
+		endedAt: asIsoTimestamp$1(row.endedAt),
+		entityName: row.entityName == null ? null : String(row.entityName),
+		entityType: row.entityType == null ? null : String(row.entityType),
+		environment: row.environment == null ? null : String(row.environment),
+		status: row.status
+	};
+}
 async function queryTraces(client, schema, plan, timeoutMs) {
+	if (plan.paginationMode === "delta") {
+		assertDeltaPollingEnabled();
+		const watermark = coreStorage.getTraceQueryDeltaWatermark(plan, "pg");
+		if (watermark !== void 0) decodeTraceDeltaWatermark(watermark);
+		const resolvedTimeoutMs = coreStorage.resolveTraceQueryTimeoutMs(timeoutMs);
+		const deadline = performance.now() + resolvedTimeoutMs;
+		return runWithPostgresTraceQueryTimeout(client, resolvedTimeoutMs, async (transaction) => {
+			await setRemainingTimeout(transaction, deadline);
+			const horizon = await readSafeXactHorizon(transaction);
+			let rows = [];
+			if (watermark !== void 0) {
+				await setRemainingTimeout(transaction, deadline);
+				const query = compilePostgresTraceQuery(schema, plan, "data", horizon);
+				rows = await transaction.any(query.text, query.values);
+			}
+			const visible = rows.slice(0, plan.limit);
+			const last = visible.at(-1);
+			return coreStorage.traceQueryResponseSchema.parse({
+				traces: visible.map(traceRowToResult),
+				delta: {
+					limit: plan.limit,
+					hasMore: rows.length > plan.limit
+				},
+				deltaCursor: coreStorage.encodeTraceQueryDeltaCursor(plan, "pg", last ? encodeDeltaCursor(last.xactId, last.cursorId) : emptyDeltaWatermark(horizon, watermark))
+			});
+		}, { repeatableRead: true });
+	}
 	if (plan.paginationMode === "page") {
 		const resolvedTimeoutMs = coreStorage.resolveTraceQueryTimeoutMs(timeoutMs);
 		const deadline = performance.now() + resolvedTimeoutMs;
 		const countQuery = compilePostgresTraceQuery(schema, plan, "count");
 		const dataQuery = compilePostgresTraceQuery(schema, plan);
-		const { total, rows } = await runWithPostgresTraceQueryTimeout(client, resolvedTimeoutMs, async (transaction) => {
+		const { total, rows, deltaCursor } = await runWithPostgresTraceQueryTimeout(client, resolvedTimeoutMs, async (transaction) => {
+			let deltaCursor;
+			if (deltaPollingFeatureEnabled() && typeof coreStorage.encodeTraceQueryDeltaCursor === "function") {
+				await setRemainingTimeout(transaction, deadline);
+				const horizon = await readSafeXactHorizon(transaction);
+				deltaCursor = coreStorage.encodeTraceQueryDeltaCursor(plan, "pg", encodeDeltaCursor(horizon, 0));
+			}
+			if (deltaCursor !== void 0) await setRemainingTimeout(transaction, deadline);
 			const countRows = await transaction.any(countQuery.text, countQuery.values);
 			const remainingTimeoutMs = Math.floor(deadline - performance.now());
 			if (remainingTimeoutMs <= 0) throw new coreStorage.TraceQueryExecutionError();
@@ -17802,29 +17935,14 @@ async function queryTraces(client, schema, plan, timeoutMs) {
 			const rows = await transaction.any(dataQuery.text, dataQuery.values);
 			return {
 				total: Number(countRows[0]?.count ?? 0),
-				rows
+				rows,
+				deltaCursor
 			};
 		}, { repeatableRead: true });
-		const traces = rows.map((row) => ({
-			traceId: String(row.traceId),
-			rootSpanId: String(row.rootSpanId),
-			name: row.name,
-			entityId: row.entityId ?? null,
-			parentSpanId: row.parentSpanId ?? null,
-			createdAt: asIsoTimestamp$1(row.startedAt),
-			metadata: row.metadata ?? null,
-			inputPreview: coreStorage.buildInputPreview(row.input) ?? null,
-			threadId: row.threadId == null ? null : String(row.threadId),
-			resourceId: row.resourceId == null ? null : String(row.resourceId),
-			startedAt: asIsoTimestamp$1(row.startedAt),
-			endedAt: asIsoTimestamp$1(row.endedAt),
-			entityName: row.entityName == null ? null : String(row.entityName),
-			entityType: row.entityType == null ? null : String(row.entityType),
-			environment: row.environment == null ? null : String(row.environment),
-			status: row.status
-		}));
+		const traces = rows.map(traceRowToResult);
 		return coreStorage.traceQueryResponseSchema.parse({
 			traces,
+			...deltaCursor === void 0 ? {} : { deltaCursor },
 			pagination: {
 				total,
 				page: plan.page,
@@ -17847,24 +17965,7 @@ async function queryTraces(client, schema, plan, timeoutMs) {
 			}) : null }
 		});
 	}
-	const traces = visibleRows.map((row) => ({
-		traceId: String(row.traceId),
-		rootSpanId: String(row.rootSpanId),
-		name: row.name,
-		entityId: row.entityId ?? null,
-		parentSpanId: row.parentSpanId ?? null,
-		createdAt: asIsoTimestamp$1(row.startedAt),
-		metadata: row.metadata ?? null,
-		inputPreview: coreStorage.buildInputPreview(row.input) ?? null,
-		threadId: row.threadId == null ? null : String(row.threadId),
-		resourceId: row.resourceId == null ? null : String(row.resourceId),
-		startedAt: asIsoTimestamp$1(row.startedAt),
-		endedAt: asIsoTimestamp$1(row.endedAt),
-		entityName: row.entityName == null ? null : String(row.entityName),
-		entityType: row.entityType == null ? null : String(row.entityType),
-		environment: row.environment == null ? null : String(row.environment),
-		status: row.status
-	}));
+	const traces = visibleRows.map(traceRowToResult);
 	const last = traces.at(-1);
 	return coreStorage.traceQueryResponseSchema.parse({
 		traces,
@@ -18603,7 +18704,7 @@ async function dangerouslyClearTracing(client, schema) {
 * Use it through `MastraCompositeStore` with a dedicated Postgres connection.
 */
 function wrapError(op, error, details) {
-	if (error instanceof MastraError || error instanceof coreStorage.TraceQueryExecutionError || error instanceof coreStorage.TraceQueryResourceLimitError) throw error;
+	if (error instanceof MastraError || error instanceof coreStorage.TraceQueryCursorError || error instanceof coreStorage.TraceQueryExecutionError || error instanceof coreStorage.TraceQueryResourceLimitError) throw error;
 	throw new MastraError({
 		id: createStorageErrorId("PG", op, "FAILED"),
 		domain: ErrorDomain.STORAGE,
@@ -22293,6 +22394,7 @@ const WORKFLOW_SNAPSHOT_STATUS_INDEX = "mastra_workflow_snapshot_name_status_cre
 * Schema-prefixed name of the status index, lowercased and truncated the same way Postgres
 * stores it, so the init snapshot's index set answers "does it exist?" without a probe or a
 * no-op `CREATE INDEX` (schema-prefixed names routinely exceed the 63-byte limit).
+* Exported for tests.
 */
 function workflowSnapshotStatusIndexName(schemaName) {
 	return buildConstraintName({
@@ -22310,6 +22412,48 @@ function workflowSnapshotStatusIndexSQL(indexName, schemaName) {
 		schemaName: getSchemaName(schemaName)
 	})} (workflow_name, (snapshot ->> 'status'), "createdAt" DESC)`;
 }
+/** Base name (before any schema prefix) of the expression index backing the threadId filter. */
+const WORKFLOW_SNAPSHOT_THREAD_ID_INDEX = "mastra_workflow_snapshot_threadid_idx";
+/**
+* Schema-prefixed name of the threadId index (see workflowSnapshotStatusIndexName).
+*
+* Unlike the status index, truncation appends a collision hash: both index names share the
+* long `<schema>_mastra_workflow_snapshot_` prefix, so with a schema name of 37+ bytes plain
+* truncation collapses them to the same 63-byte identifier and `CREATE INDEX IF NOT EXISTS`
+* silently skips this index. The status index keeps plain truncation because its truncated
+* name already exists in deployed catalogs; this index is new and free to adopt the rule.
+* Exported for tests.
+*/
+function workflowSnapshotThreadIdIndexName(schemaName) {
+	return buildConstraintName({
+		baseName: WORKFLOW_SNAPSHOT_THREAD_ID_INDEX,
+		schemaName: schemaName && schemaName !== "public" ? schemaName : void 0,
+		hashWhenTruncated: true
+	});
+}
+/**
+* Expression extracting the thread id embedded in a snapshot (jsonb columns only). Mirrors
+* the canonical extraction in `@mastra/core` (`getSnapshotMemoryInfo`), which reads one of
+* two layouts:
+* 1. agentic-loop: `context.<suspended step>.suspendPayload.__streamState.messageList.memoryInfo.threadId`
+* 2. durable loop: `context.input.messageListState.memoryInfo.threadId`
+*
+* `jsonb_path_query_first(jsonb, jsonpath)` is IMMUTABLE, so the expression is valid in an
+* expression index. The WHERE clause in listWorkflowRuns() must use this exact expression
+* text so the planner can match it against the index. If the snapshot layout changes in
+* core, this expression must be updated in lockstep or it will wrongly exclude rows.
+*/
+const WORKFLOW_SNAPSHOT_THREAD_ID_EXPR = `COALESCE(jsonb_path_query_first(snapshot, '$.context.* ? (@.status == "suspended").suspendPayload.__streamState.messageList.memoryInfo.threadId') #>> '{}', snapshot #>> '{context,input,messageListState,memoryInfo,threadId}')`;
+/**
+* Expression index on the snapshot-embedded thread id so listWorkflowRuns() threadId filters
+* (Agent.listSuspendedRuns) can use an index instead of detoasting every snapshot.
+*/
+function workflowSnapshotThreadIdIndexSQL(indexName, schemaName) {
+	return `CREATE INDEX IF NOT EXISTS "${indexName}" ON ${getTableName({
+		indexName: TABLE_WORKFLOW_SNAPSHOT,
+		schemaName: getSchemaName(schemaName)
+	})} ((${WORKFLOW_SNAPSHOT_THREAD_ID_EXPR}))`;
+}
 var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 	#db;
 	#schema;
@@ -22382,6 +22526,7 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 		}));
 		for (const idx of WorkflowsPG.getDefaultIndexDefs(schemaPrefix)) statements.push(generateIndexSQL(idx, schemaName));
 		statements.push(`${workflowSnapshotStatusIndexSQL(workflowSnapshotStatusIndexName(parsedSchema), schemaName)};`);
+		statements.push(`${workflowSnapshotThreadIdIndexSQL(workflowSnapshotThreadIdIndexName(parsedSchema), schemaName)};`);
 		return statements;
 	}
 	/**
@@ -22408,6 +22553,12 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 		} catch (error) {
 			this.logger?.warn?.(`Failed to create index ${indexName}:`, error);
 		}
+		const threadIdIndexName = workflowSnapshotThreadIdIndexName(this.#schema);
+		try {
+			await this.#db.createIndexFromStatement(threadIdIndexName, workflowSnapshotThreadIdIndexSQL(threadIdIndexName, this.#schema));
+		} catch (error) {
+			this.logger?.warn?.(`Failed to create index ${threadIdIndexName}:`, error);
+		}
 	}
 	async init() {
 		await this.#db.createTable({
@@ -22688,7 +22839,7 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async listWorkflowRuns({ workflowName, fromDate, toDate, perPage, page, resourceId, status } = {}) {
+	async listWorkflowRuns({ workflowName, fromDate, toDate, perPage, page, resourceId, threadId, status } = {}) {
 		try {
 			const conditions = [];
 			const values = [];
@@ -22709,6 +22860,11 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 				values.push(resourceId);
 				paramIndex++;
 			} else this.logger?.warn?.(`[${TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			if (threadId) if (await this.#db.getColumnType(TABLE_WORKFLOW_SNAPSHOT, "snapshot") === "jsonb") {
+				conditions.push(`${WORKFLOW_SNAPSHOT_THREAD_ID_EXPR} = $${paramIndex}`);
+				values.push(threadId);
+				paramIndex++;
+			} else this.logger?.warn?.(`[${TABLE_WORKFLOW_SNAPSHOT}] snapshot column is not jsonb. Skipping threadId filter.`);
 			if (fromDate) {
 				conditions.push(`"createdAt" >= $${paramIndex}`);
 				values.push(fromDate);