@mastra/react 1.12.0-alpha.9 → 1.13.0-alpha.0

package/dist/hooks/traces/index.cjs

@@ -19,7 +19,7 @@ let _mastra_core_observability = require("@mastra/core/observability");
 * through to the store's discovery refresh. Matching the server TTL keeps the
 * client from asking more often than the answer can change.
 */
-const DISCOVERY_STALE_TIME = 300 * 1e3;
+const DISCOVERY_STALE_TIME = 3e5;
 //#endregion
 //#region src/hooks/traces/use-branch.ts
 /**
@@ -136,7 +136,7 @@ const useServiceNames = ({ queryOptions } = {}) => {
 };
 //#endregion
 //#region src/hooks/traces/use-span-detail.ts
-const IMMUTABLE_CACHE_TIME$1 = 1e3 * 60 * 60 * 24 * 30;
+const IMMUTABLE_CACHE_TIME$1 = 2592e6;
 /**
 * Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
 */
@@ -201,7 +201,7 @@ function useThreadHasOtherTraces({ threadId, queryOptions }) {
 }
 //#endregion
 //#region src/hooks/traces/use-trace-light-spans.ts
-const IMMUTABLE_CACHE_TIME = 1e3 * 60 * 60 * 24 * 30;
+const IMMUTABLE_CACHE_TIME = 2592e6;
 /**
 * Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
 */
@@ -320,6 +320,8 @@ function useTraceOrBranchSpans({ traceId, anchorSpanId, listMode, depth, queryOp
 //#endregion
 //#region src/hooks/traces/use-trace-query.ts
 const TRACE_QUERY_PER_PAGE = 25;
+/** Max traces per delta request; the server caps `limit` at 100. */
+const TRACE_QUERY_DELTA_LIMIT = 100;
 function getTraceQueryNextPageParam(lastPage) {
 	return lastPage?.page.next ?? void 0;
 }
@@ -369,16 +371,101 @@ function selectLegacyTraceQueryTraces(data) {
 function getLegacyTraceQueryNextPageParam(lastPage) {
 	return lastPage.pagination?.hasMore ? lastPage.pagination.page + 1 : void 0;
 }
+/** Cache key of `useTraceQuery`'s trace-query list. Pass the same `query` and `limit` to share it. */
+const traceQueryKey = (query, limit = 25) => [
+	"trace-query",
+	query,
+	limit
+];
+function traceSortValue(trace, field) {
+	if (field === "timeToFirstChunkMs") return trace.timeToFirstChunkMs ?? null;
+	const value = trace[field];
+	return value == null ? null : Date.parse(value);
+}
+/** Mirrors the server's keyset order: empty values last in both directions, ties by ascending `traceId`. */
+function compareTraces(orderBy) {
+	return (a, b) => {
+		const va = traceSortValue(a, orderBy.field);
+		const vb = traceSortValue(b, orderBy.field);
+		if (va !== vb) {
+			if (va === null) return 1;
+			if (vb === null) return -1;
+			return orderBy.direction === "asc" ? va - vb : vb - va;
+		}
+		return a.traceId < b.traceId ? -1 : a.traceId > b.traceId ? 1 : 0;
+	};
+}
+/**
+* Merges delta-polled traces into the pages of a `useTraceQuery` list, without mutating `data`.
+* A trace already on a page is replaced in place when its sort value is unchanged; otherwise it is
+* removed and placed again like a new trace (sorting by `endedAt`, a running trace moves once it
+* ends). A new trace goes into the first page whose last row sorts after it; when no loaded page does, it is
+* appended to the last page if that is the end of the list, and skipped otherwise, since keyset
+* pagination returns it once the user scrolls there. Page cursors are kept as they are, and `data`
+* itself is returned when nothing changed.
+*/
+function mergeTraceQueryDelta(data, traces, orderBy) {
+	if (traces.length === 0 || data.pages.length === 0) return data;
+	const incoming = new Map(traces.map((trace) => [trace.traceId, trace]));
+	const rows = data.pages.map((page) => page.traces);
+	const changed = /* @__PURE__ */ new Set();
+	const write = (pageIndex, next) => {
+		rows[pageIndex] = next;
+		changed.add(pageIndex);
+	};
+	const sortBy = orderBy?.[0] ?? {
+		field: "startedAt",
+		direction: "desc"
+	};
+	const compare = compareTraces(sortBy);
+	const replacedInPlace = /* @__PURE__ */ new Set();
+	rows.forEach((pageRows, pageIndex) => {
+		if (!pageRows.some((row) => incoming.has(row.traceId))) return;
+		const next = [];
+		for (const row of pageRows) {
+			const update = incoming.get(row.traceId);
+			if (!update) next.push(row);
+			else if (traceSortValue(update, sortBy.field) === traceSortValue(row, sortBy.field)) {
+				next.push(update);
+				replacedInPlace.add(row.traceId);
+			}
+		}
+		write(pageIndex, next);
+	});
+	for (const traceId of replacedInPlace) incoming.delete(traceId);
+	const lastIndex = rows.length - 1;
+	for (const trace of incoming.values()) {
+		let pageIndex = rows.findIndex((pageRows) => {
+			const last = pageRows[pageRows.length - 1];
+			return last !== void 0 && compare(trace, last) < 0;
+		});
+		if (pageIndex === -1) {
+			if (data.pages[lastIndex].page.next !== null) continue;
+			pageIndex = lastIndex;
+		}
+		const pageRows = rows[pageIndex];
+		const at = pageRows.findIndex((row) => compare(trace, row) < 0);
+		write(pageIndex, at === -1 ? [...pageRows, trace] : [
+			...pageRows.slice(0, at),
+			trace,
+			...pageRows.slice(at)
+		]);
+	}
+	if (changed.size === 0) return data;
+	return {
+		...data,
+		pages: data.pages.map((page, pageIndex) => changed.has(pageIndex) ? {
+			...page,
+			traces: rows[pageIndex]
+		} : page)
+	};
+}
 /** Queries traces with cursor pagination and viewport-driven loading. */
 function useTraceQuery({ query, limit = 25, enabled = true, withQueryTrace = true, legacyFilters, queryOptions }) {
 	const client = require_mastra_client_context.useMastraClient();
 	const { inView, setRef: setEndOfListElement } = require_use_in_view.useInView();
 	const queryResult = (0, _tanstack_react_query.useInfiniteQuery)({
-		queryKey: [
-			"trace-query",
-			query,
-			limit
-		],
+		queryKey: traceQueryKey(query, limit),
 		queryFn: query ? async ({ pageParam }) => {
 			const response = await new _mastra_client_js.MastraClient({
 				...client.options,
@@ -456,6 +543,194 @@ function useTraceQuery({ query, limit = 25, enabled = true, withQueryTrace = tru
 		setEndOfListElement
 	};
 }
+function omitOrderBy({ orderBy: _orderBy, ...rest }) {
+	return rest;
+}
+/** Request timeouts and rate limits clear up on their own, unlike the other 4xx refusals. */
+const TRANSIENT_CLIENT_ERROR_STATUSES = /* @__PURE__ */ new Set([408, 429]);
+/** The server refused the request or does not support delta polling; polling again cannot change that. */
+function isRejectedDeltaRequest(error) {
+	if (!(error instanceof _mastra_client_js.MastraClientError) || TRANSIENT_CLIENT_ERROR_STATUSES.has(error.status)) return false;
+	return error.status >= 400 && error.status < 500 || error.status === 501;
+}
+const isCursorConflict = (error) => error instanceof _mastra_client_js.MastraClientError && error.status === 409;
+/**
+* Polls `queryTraces({ mode: 'delta' })` and merges new or updated traces into the list of a
+* `useTraceQuery` rendered with the same `query` and `limit`. The first request only establishes
+* the server cursor; each later poll drains every batch since that cursor. A cursor conflict (409)
+* starts over with a new cursor. A poll that returns while the list is loading a page, or before
+* the list has loaded at all, keeps its cursor and asks again on the next poll.
+*
+* The cursor is keyed on the query without `orderBy` (delta polls cannot sort) and on `limit`, so
+* re-sorting the list keeps polling from the same cursor, and lists with different page sizes each
+* get their own cursor.
+*
+* Requires the `deltaPolling` capability (see `useTraceQueryDeltaPollingAvailable`). The list's
+* `timeRange.to` must not move between polls, so a live list needs a `to` in the future.
+*
+* Known limitation: the cursor is established in parallel with the list's first page, so a trace
+* that completes between the first page's read and the cursor can be missed until the list is
+* refetched. Traces returned by both are merged by `traceId`.
+*/
+function useTraceQueryLatest({ query, limit = 25, enabled = true, refetchInterval = false, queryOptions }) {
+	const client = require_mastra_client_context.useMastraClient();
+	const queryClient = (0, _tanstack_react_query.useQueryClient)();
+	const deltaQuery = query && omitOrderBy(query);
+	const queryKey = [
+		"trace-query-latest",
+		deltaQuery,
+		limit
+	];
+	return (0, _tanstack_react_query.useQuery)({
+		queryKey,
+		queryFn: query && deltaQuery ? async () => {
+			const mastra = new _mastra_client_js.MastraClient({
+				...client.options,
+				retries: 0
+			});
+			const bootstrap = async () => {
+				return { deltaCursor: (await mastra.queryTraces({
+					...deltaQuery,
+					mode: "delta"
+				})).deltaCursor };
+			};
+			const previous = queryClient.getQueryData(queryKey);
+			if (!previous) return bootstrap();
+			const traces = [];
+			let deltaCursor = previous.deltaCursor;
+			try {
+				for (let hasMore = true; hasMore;) {
+					const response = await mastra.queryTraces({
+						...deltaQuery,
+						mode: "delta",
+						after: deltaCursor,
+						limit: 100
+					});
+					traces.push(...response.traces);
+					deltaCursor = response.deltaCursor;
+					hasMore = response.delta.hasMore;
+				}
+			} catch (error) {
+				if (isCursorConflict(error)) return bootstrap();
+				throw error;
+			}
+			const listKey = traceQueryKey(query, limit);
+			const listState = queryClient.getQueryState(listKey);
+			if (!listState?.data || listState.fetchStatus === "fetching") return previous;
+			queryClient.setQueryData(listKey, (data) => data ? mergeTraceQueryDelta(data, traces, query.orderBy) : data);
+			return { deltaCursor };
+		} : _tanstack_react_query.skipToken,
+		retry: false,
+		refetchInterval: (q) => isRejectedDeltaRequest(q.state.error) ? false : refetchInterval,
+		refetchIntervalInBackground: false,
+		enabled: enabled && !!query,
+		...queryOptions
+	});
+}
+//#endregion
+//#region src/hooks/traces/use-query-spans.ts
+const SPAN_QUERY_PER_PAGE = 25;
+const selectSpans = (data) => data.pages.flatMap((page) => page.spans);
+/** Queries completed spans with cursor pagination and viewport-driven loading. */
+function useQuerySpans({ query, limit = 25, enabled = true, queryOptions }) {
+	const client = require_mastra_client_context.useMastraClient();
+	const { inView, setRef: setEndOfListElement } = require_use_in_view.useInView();
+	const { data, hasNextPage, isFetchingNextPage, fetchNextPage, isLoading, isFetching, isError, error, refetch, isFetchNextPageError } = (0, _tanstack_react_query.useInfiniteQuery)({
+		queryKey: [
+			"span-query",
+			query,
+			limit
+		],
+		queryFn: query ? ({ pageParam }) => client.querySpans({
+			...query,
+			page: pageParam ? {
+				limit,
+				after: pageParam
+			} : { limit }
+		}) : _tanstack_react_query.skipToken,
+		initialPageParam: void 0,
+		getNextPageParam: (lastPage) => lastPage.page.next ?? void 0,
+		select: selectSpans,
+		retry: false,
+		placeholderData: _tanstack_react_query.keepPreviousData,
+		enabled,
+		...queryOptions
+	});
+	(0, react.useEffect)(() => {
+		if (enabled && inView && hasNextPage && !isFetching && !isFetchNextPageError) fetchNextPage();
+	}, [
+		enabled,
+		inView,
+		hasNextPage,
+		isFetching,
+		isFetchNextPageError,
+		fetchNextPage
+	]);
+	return {
+		spans: data,
+		hasNextPage,
+		isFetchingNextPage,
+		fetchNextPage: () => void fetchNextPage(),
+		setEndOfListElement,
+		isLoading,
+		isFetching,
+		isError,
+		error,
+		refetch: () => void refetch()
+	};
+}
+//#endregion
+//#region src/hooks/traces/use-query-threads.ts
+const THREAD_QUERY_PER_PAGE = 25;
+const selectThreads = (data) => data.pages.flatMap((page) => page.threads);
+/** Queries thread rows with cursor pagination and viewport-driven loading. */
+function useQueryThreads({ query, limit = 25, enabled = true, queryOptions }) {
+	const client = require_mastra_client_context.useMastraClient();
+	const { inView, setRef: setEndOfListElement } = require_use_in_view.useInView();
+	const { data, hasNextPage, isFetchingNextPage, fetchNextPage, isLoading, isFetching, isError, error, refetch, isFetchNextPageError } = (0, _tanstack_react_query.useInfiniteQuery)({
+		queryKey: [
+			"thread-query",
+			query,
+			limit
+		],
+		queryFn: query ? ({ pageParam }) => client.queryTraceThreads({
+			...query,
+			page: pageParam ? {
+				limit,
+				after: pageParam
+			} : { limit }
+		}) : _tanstack_react_query.skipToken,
+		initialPageParam: void 0,
+		getNextPageParam: (lastPage) => lastPage.page.next ?? void 0,
+		select: selectThreads,
+		retry: false,
+		placeholderData: _tanstack_react_query.keepPreviousData,
+		enabled,
+		...queryOptions
+	});
+	(0, react.useEffect)(() => {
+		if (enabled && inView && hasNextPage && !isFetching && !isFetchNextPageError) fetchNextPage();
+	}, [
+		enabled,
+		inView,
+		hasNextPage,
+		isFetching,
+		isFetchNextPageError,
+		fetchNextPage
+	]);
+	return {
+		threads: data,
+		hasNextPage,
+		isFetchingNextPage,
+		fetchNextPage: () => void fetchNextPage(),
+		setEndOfListElement,
+		isLoading,
+		isFetching,
+		isError,
+		error,
+		refetch: () => void refetch()
+	};
+}
 //#endregion
 //#region src/hooks/traces/use-trace-usage.ts
 const INPUT_TOKEN_METRIC = "mastra_model_total_input_tokens";
@@ -552,7 +827,7 @@ const DEFAULT_POLLING_CONFIG = {
 	deltaLimit: 100,
 	pageModeRefetchIntervalMs: 1e4,
 	page0StatusRefreshIntervalMs: 6e4,
-	idleGuardThresholdMs: 15 * 6e4,
+	idleGuardThresholdMs: 9e5,
 	minRefetchSpinMs: 400,
 	deltaHighlightMs: 1e3
 };
@@ -1132,7 +1407,10 @@ function useTraceColumnPreferencesStorageKey() {
 //#endregion
 exports.DISCOVERY_STALE_TIME = DISCOVERY_STALE_TIME;
 exports.ROOT_ENTITY_TYPES = ROOT_ENTITY_TYPES;
+exports.SPAN_QUERY_PER_PAGE = SPAN_QUERY_PER_PAGE;
+exports.THREAD_QUERY_PER_PAGE = THREAD_QUERY_PER_PAGE;
 exports.TRACES_PER_PAGE = TRACES_PER_PAGE;
+exports.TRACE_QUERY_DELTA_LIMIT = TRACE_QUERY_DELTA_LIMIT;
 exports.TRACE_QUERY_PER_PAGE = TRACE_QUERY_PER_PAGE;
 exports.createTraceQueryValuesResolver = createTraceQueryValuesResolver;
 exports.getLegacyTraceQueryNextPageParam = getLegacyTraceQueryNextPageParam;
@@ -1140,6 +1418,7 @@ exports.getTraceQueryNextPageParam = getTraceQueryNextPageParam;
 exports.getTracesNextPageParam = getTracesNextPageParam;
 exports.lightSpanToTraceQueryTrace = lightSpanToTraceQueryTrace;
 exports.mergeDeltaIntoPage0 = mergeDeltaIntoPage0;
+exports.mergeTraceQueryDelta = mergeTraceQueryDelta;
 exports.refreshPage0Rows = refreshPage0Rows;
 exports.selectLegacyTraceQueryTraces = selectLegacyTraceQueryTraces;
 exports.selectTraceQueryTraces = selectTraceQueryTraces;
@@ -1147,6 +1426,7 @@ exports.selectUniqueTraces = selectUniqueTraces;
 exports.shouldPinLightList = shouldPinLightList;
 exports.shouldResetAfterIdle = shouldResetAfterIdle;
 exports.traceQueryFieldsQueryKey = traceQueryFieldsQueryKey;
+exports.traceQueryKey = traceQueryKey;
 exports.traceSpansQueryOptions = traceSpansQueryOptions;
 exports.useBranch = useBranch;
 exports.useCreateFeedback = useCreateFeedback;
@@ -1154,6 +1434,8 @@ exports.useDeleteFeedback = useDeleteFeedback;
 exports.useEntityNames = useEntityNames;
 exports.useEnvironments = useEnvironments;
 exports.useFetchTraceSpans = useFetchTraceSpans;
+exports.useQuerySpans = useQuerySpans;
+exports.useQueryThreads = useQueryThreads;
 exports.useServiceNames = useServiceNames;
 exports.useSpanDetail = useSpanDetail;
 exports.useSpanFeedback = useSpanFeedback;
@@ -1165,6 +1447,7 @@ exports.useTraceLightSpans = useTraceLightSpans;
 exports.useTraceMetadataFilterFields = useTraceMetadataFilterFields;
 exports.useTraceOrBranchSpans = useTraceOrBranchSpans;
 exports.useTraceQuery = useTraceQuery;
+exports.useTraceQueryLatest = useTraceQueryLatest;
 exports.useTraceSpans = useTraceSpans;
 exports.useTraceSpansQueries = useTraceSpansQueries;
 exports.useTraceUsage = useTraceUsage;