@mastra/react 1.7.3-alpha.3 → 1.8.0-alpha.4

package/dist/hooks/traces/index.js

@@ -0,0 +1,1129 @@
+import { n as useMastraClient } from "../../mastra-client-context-Bx_g84YB.js";
+import { t as useInView } from "../../use-in-view-C9sYPGRm.js";
+import { n as is403ForbiddenError } from "../../query-utils-D1NgFnWU.js";
+import { t as getOrCreate } from "../../map-CDv4fbu4.js";
+import { t as getFeedbackRefetchInterval } from "../../feedback-refetch-interval-DLHzQoVV.js";
+import { MastraClient, MastraClientError } from "@mastra/client-js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { keepPreviousData, queryOptions, skipToken, useInfiniteQuery, useMutation, useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import { EntityType } from "@mastra/core/observability";
+//#region src/hooks/traces/discovery-cache.ts
+/**
+* How long discovery results (tags, environments, service names, entity
+* names) stay fresh on the client.
+*
+* Discovery values are filter suggestions that change slowly, and the server
+* caches them for 5 minutes anyway. Without a staleTime, React Query refetches
+* on every mount and window focus, which pushes those refetches straight
+* 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;
+//#endregion
+//#region src/hooks/traces/use-branch.ts
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+function useBranch({ traceId, spanId, depth, queryOptions }) {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: [
+			"branch",
+			traceId,
+			spanId,
+			depth
+		],
+		queryFn: async () => {
+			if (!traceId || !spanId) throw new Error("traceId and spanId are required");
+			return client.getBranch({
+				traceId,
+				spanId,
+				depth
+			});
+		},
+		staleTime: 0,
+		...queryOptions
+	});
+}
+//#endregion
+//#region src/hooks/traces/types.ts
+const ROOT_ENTITY_TYPES = {
+	AGENT: "agent",
+	WORKFLOW: "workflow_run",
+	SCORER: "scorer",
+	INGEST: "rag_ingestion"
+};
+//#endregion
+//#region src/hooks/traces/use-entity-names.ts
+function resolveEntityType(entityType) {
+	return Object.values(EntityType).find((candidate) => candidate === entityType);
+}
+const useEntityNames = ({ entityType, rootOnly = false, queryOptions } = {}) => {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: entityType ? [
+			"observability-entity-names",
+			"by-type",
+			entityType
+		] : [
+			"observability-entity-names",
+			"all",
+			rootOnly ? "root-only" : "all-types"
+		],
+		queryFn: async () => {
+			try {
+				if (entityType) {
+					const resolvedEntityType = resolveEntityType(entityType);
+					if (!resolvedEntityType) return { names: [] };
+					return await client.getEntityNames({ entityType: resolvedEntityType });
+				}
+				if (!rootOnly) return await client.getEntityNames();
+				const responses = await Promise.all(Object.values(ROOT_ENTITY_TYPES).map((rootEntityType) => {
+					const resolvedEntityType = resolveEntityType(rootEntityType);
+					if (!resolvedEntityType) return { names: [] };
+					return client.getEntityNames({ entityType: resolvedEntityType });
+				}));
+				return { names: Array.from(new Set(responses.flatMap((response) => response?.names ?? []))).sort() };
+			} catch {
+				return { names: [] };
+			}
+		},
+		select: (data) => data?.names ?? [],
+		retry: false,
+		staleTime: DISCOVERY_STALE_TIME,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-environments.ts
+const useEnvironments = ({ queryOptions } = {}) => {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: ["observability-environments"],
+		queryFn: async () => {
+			try {
+				return await client.getEnvironments();
+			} catch {
+				return { environments: [] };
+			}
+		},
+		select: (data) => data?.environments ?? [],
+		retry: false,
+		staleTime: DISCOVERY_STALE_TIME,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-service-names.ts
+const useServiceNames = ({ queryOptions } = {}) => {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: ["observability-service-names"],
+		queryFn: async () => {
+			try {
+				return await client.getServiceNames();
+			} catch {
+				return { serviceNames: [] };
+			}
+		},
+		select: (data) => data?.serviceNames ?? [],
+		retry: false,
+		staleTime: DISCOVERY_STALE_TIME,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-span-detail.ts
+const IMMUTABLE_CACHE_TIME$1 = 1e3 * 60 * 60 * 24 * 30;
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+function useSpanDetail({ traceId, spanId, queryOptions }) {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: [
+			"span-detail",
+			traceId,
+			spanId
+		],
+		queryFn: async () => {
+			if (!traceId || !spanId) throw new Error("Trace ID and Span ID are required");
+			return client.getSpan(traceId, spanId);
+		},
+		staleTime: (query) => {
+			if (query.state.data?.span?.endedAt) return IMMUTABLE_CACHE_TIME$1;
+			return 0;
+		},
+		...queryOptions
+	});
+}
+//#endregion
+//#region src/hooks/traces/use-tags.ts
+const useTags = ({ queryOptions } = {}) => {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: ["observability-tags"],
+		queryFn: async () => {
+			try {
+				return await client.getTags();
+			} catch {
+				return { tags: [] };
+			}
+		},
+		select: (data) => data?.tags ?? [],
+		retry: false,
+		staleTime: DISCOVERY_STALE_TIME,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-thread-has-other-traces.ts
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+function useThreadHasOtherTraces({ threadId, queryOptions }) {
+	const client = useMastraClient();
+	const { data } = useQuery({
+		queryKey: ["thread-trace-count", threadId],
+		queryFn: () => client.listTracesLight({
+			filters: { threadId: threadId ?? "" },
+			pagination: {
+				page: 0,
+				perPage: 25
+			}
+		}),
+		select: (response) => (response.spans?.length ?? 0) > 1,
+		...queryOptions
+	});
+	return data ?? false;
+}
+//#endregion
+//#region src/hooks/traces/use-trace-light-spans.ts
+const IMMUTABLE_CACHE_TIME = 1e3 * 60 * 60 * 24 * 30;
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+function useTraceLightSpans({ traceId, queryOptions }) {
+	const client = useMastraClient();
+	return useQuery({
+		queryKey: ["trace-light-spans", traceId],
+		queryFn: async () => {
+			if (!traceId) throw new Error("Trace ID is required");
+			return await client.getTraceLight(traceId);
+		},
+		staleTime: (query) => {
+			if (query.state.data?.spans.every((d) => Boolean(d.endedAt))) return IMMUTABLE_CACHE_TIME;
+			return 0;
+		},
+		...queryOptions
+	});
+}
+//#endregion
+//#region src/hooks/traces/use-trace-spans.ts
+const traceSpansQueryOptions = (client, traceId) => queryOptions({
+	queryKey: ["trace-spans", traceId],
+	queryFn: async () => {
+		if (!traceId) throw new Error("Trace ID is required");
+		return await client.getTrace(traceId);
+	},
+	staleTime: 0
+});
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+function useTraceSpans({ traceId, passive = false, queryOptions }) {
+	const client = useMastraClient();
+	const { queryKey, queryFn, enabled, staleTime } = traceSpansQueryOptions(client, traceId);
+	return useQuery({
+		queryKey,
+		queryFn,
+		enabled,
+		staleTime,
+		refetchOnMount: !passive,
+		refetchOnWindowFocus: !passive,
+		refetchOnReconnect: !passive,
+		...queryOptions
+	});
+}
+/**
+* Returns a function that loads a full trace through the shared `trace-spans` cache, so an
+* imperative read (e.g. an export) and the trace panel always see the same payload.
+*/
+function useFetchTraceSpans() {
+	const client = useMastraClient();
+	const queryClient = useQueryClient();
+	return (traceId) => queryClient.fetchQuery(traceSpansQueryOptions(client, traceId));
+}
+/**
+* Observes the `trace-spans` query of several traces at once and projects each one with `select`.
+* Traces still loading (or failed) yield `fallback(traceId)` so the result always lines up with `traceIds`.
+*/
+function useTraceSpansQueries({ traceIds, select, fallback, queryOptions }) {
+	const client = useMastraClient();
+	return useQueries({
+		queries: traceIds.map((traceId) => ({
+			...traceSpansQueryOptions(client, traceId),
+			refetchOnMount: false,
+			refetchOnWindowFocus: false,
+			refetchOnReconnect: false,
+			select: (data) => select(traceId, data),
+			...queryOptions
+		})),
+		combine: (results) => results.map((result, index) => result.data === void 0 ? fallback(traceIds[index] ?? "") : result.data)
+	});
+}
+//#endregion
+//#region src/hooks/traces/use-trace-or-branch-spans.ts
+/**
+* Unified data source for the trace/span detail panel. Returns trace spans (full tree from the
+* root) in traces mode, or branch spans (subtree rooted at `anchorSpanId`) in branches mode.
+* Only the active query fires; the inactive one is disabled via its `enabled` flag.
+*
+* Both modes carry full span payloads: the panel renders and searches them, so a lightweight
+* projection here would hide content from the reader looking straight at it.
+*/
+function useTraceOrBranchSpans({ traceId, anchorSpanId, listMode, depth, queryOptions }) {
+	const isBranches = listMode === "branches";
+	const traceQuery = useTraceSpans({
+		traceId: isBranches ? null : traceId,
+		queryOptions: {
+			enabled: !isBranches && !!traceId,
+			...queryOptions?.trace
+		}
+	});
+	const branchQuery = useBranch({
+		traceId: isBranches ? traceId : null,
+		spanId: isBranches ? anchorSpanId : null,
+		depth,
+		queryOptions: {
+			enabled: isBranches && !!traceId && !!anchorSpanId,
+			...queryOptions?.branch
+		}
+	});
+	if (isBranches) return {
+		spans: branchQuery.data?.spans,
+		anchorSpanId: anchorSpanId ?? void 0,
+		isLoading: branchQuery.isLoading,
+		isError: branchQuery.isError,
+		error: branchQuery.error
+	};
+	return {
+		spans: traceQuery.data?.spans,
+		anchorSpanId: void 0,
+		isLoading: traceQuery.isLoading,
+		isError: traceQuery.isError,
+		error: traceQuery.error
+	};
+}
+//#endregion
+//#region src/hooks/traces/use-trace-query.ts
+const TRACE_QUERY_PER_PAGE = 25;
+function getTraceQueryNextPageParam(lastPage) {
+	return lastPage?.page.next ?? void 0;
+}
+function selectTraceQueryTraces(data) {
+	const seen = /* @__PURE__ */ new Set();
+	return data.pages.flatMap((page) => page.traces.filter((trace) => {
+		if (seen.has(trace.traceId)) return false;
+		seen.add(trace.traceId);
+		return true;
+	}));
+}
+const toIsoString = (value) => typeof value === "string" ? value : value.toISOString();
+/** Maps a legacy light root span to a trace-query row. The light record carries no
+*  environment, so it stays null. Running spans have no `endedAt` and may carry a
+*  status outside the query API's enum; both are kept as-is (the list view handles them), hence the
+*  assertion at this compatibility boundary. */
+function lightSpanToTraceQueryTrace(span) {
+	return {
+		traceId: span.traceId,
+		rootSpanId: span.spanId,
+		name: span.name,
+		entityId: span.entityId ?? null,
+		parentSpanId: span.parentSpanId ?? null,
+		createdAt: toIsoString(span.createdAt),
+		metadata: span.metadata ?? null,
+		inputPreview: span.inputPreview ?? null,
+		threadId: span.threadId ?? null,
+		resourceId: span.resourceId ?? null,
+		startedAt: toIsoString(span.startedAt),
+		endedAt: span.endedAt == null ? span.endedAt : toIsoString(span.endedAt),
+		entityName: span.entityName ?? null,
+		entityType: span.entityType ?? null,
+		environment: null,
+		status: span.status
+	};
+}
+function selectLegacyTraceQueryTraces(data) {
+	const seen = /* @__PURE__ */ new Set();
+	return data.pages.flatMap((page) => page.spans.flatMap((span) => {
+		if (seen.has(span.traceId)) return [];
+		seen.add(span.traceId);
+		return [lightSpanToTraceQueryTrace(span)];
+	}));
+}
+function getLegacyTraceQueryNextPageParam(lastPage) {
+	return lastPage.pagination?.hasMore ? lastPage.pagination.page + 1 : void 0;
+}
+/** Queries traces with cursor pagination and viewport-driven loading. */
+function useTraceQuery({ query, limit = 25, enabled = true, withQueryTrace = true, legacyFilters, queryOptions }) {
+	const client = useMastraClient();
+	const { inView, setRef: setEndOfListElement } = useInView();
+	const queryResult = useInfiniteQuery({
+		queryKey: [
+			"trace-query",
+			query,
+			limit
+		],
+		queryFn: query ? async ({ pageParam }) => {
+			const response = await new MastraClient({
+				...client.options,
+				retries: 0
+			}).queryTraces({
+				...query,
+				page: {
+					limit,
+					after: pageParam ?? null
+				}
+			});
+			if ("traces" in response && "page" in response) return response;
+			throw new Error("Expected a cursor-paginated trace query response");
+		} : skipToken,
+		initialPageParam: void 0,
+		getNextPageParam: getTraceQueryNextPageParam,
+		select: selectTraceQueryTraces,
+		retry: false,
+		placeholderData: keepPreviousData,
+		enabled: enabled && withQueryTrace,
+		...queryOptions?.traceQuery
+	});
+	const orderBy = query?.orderBy;
+	const legacyDirection = orderBy?.[0]?.direction === "asc" ? "ASC" : "DESC";
+	const legacyResult = useInfiniteQuery({
+		queryKey: [
+			"trace-query-legacy",
+			legacyFilters,
+			limit,
+			orderBy
+		],
+		queryFn: ({ pageParam }) => client.listTracesLight({
+			filters: legacyFilters,
+			pagination: {
+				page: pageParam,
+				perPage: limit
+			},
+			orderBy: {
+				field: "startedAt",
+				direction: legacyDirection
+			}
+		}),
+		initialPageParam: 0,
+		getNextPageParam: getLegacyTraceQueryNextPageParam,
+		select: selectLegacyTraceQueryTraces,
+		retry: false,
+		placeholderData: keepPreviousData,
+		enabled: enabled && !withQueryTrace,
+		...queryOptions?.legacy
+	});
+	const { data, hasNextPage, isFetchingNextPage, fetchNextPage, isLoading, isPlaceholderData, isFetching, isRefetching, fetchStatus, isError, error, refetch, isFetchNextPageError } = withQueryTrace ? queryResult : legacyResult;
+	useEffect(() => {
+		if (enabled && inView && hasNextPage && !isFetching && !isFetchNextPageError) fetchNextPage();
+	}, [
+		enabled,
+		inView,
+		hasNextPage,
+		isFetching,
+		isFetchNextPageError,
+		fetchNextPage
+	]);
+	return {
+		data,
+		hasNextPage,
+		isFetchingNextPage,
+		fetchNextPage,
+		isLoading,
+		isPlaceholderData,
+		isFetching,
+		isRefetching,
+		fetchStatus,
+		isError,
+		error,
+		refetch,
+		setEndOfListElement
+	};
+}
+//#endregion
+//#region src/hooks/traces/use-trace-usage.ts
+const INPUT_TOKEN_METRIC = "mastra_model_total_input_tokens";
+const OUTPUT_TOKEN_METRIC = "mastra_model_total_output_tokens";
+const TRACE_IDS_PER_REQUEST = 500;
+function chunkTraceIds(traceIds) {
+	const chunks = [];
+	for (let index = 0; index < traceIds.length; index += TRACE_IDS_PER_REQUEST) chunks.push(traceIds.slice(index, index + TRACE_IDS_PER_REQUEST));
+	return chunks;
+}
+function createTraceUsageAccumulator() {
+	return {
+		estimatedCost: 0,
+		hasEstimatedCost: false,
+		costUnits: /* @__PURE__ */ new Set(),
+		hasUnknownCostUnit: false
+	};
+}
+function addBreakdown(accumulators, response) {
+	for (const group of response.groups) {
+		const traceId = group.dimensions.traceId;
+		const metricName = group.dimensions.name;
+		if (!traceId || metricName !== INPUT_TOKEN_METRIC && metricName !== OUTPUT_TOKEN_METRIC) continue;
+		const accumulator = getOrCreate(accumulators, traceId, createTraceUsageAccumulator);
+		const tokenField = metricName === INPUT_TOKEN_METRIC ? "inputTokens" : "outputTokens";
+		accumulator[tokenField] = (accumulator[tokenField] ?? 0) + group.value;
+		if (group.estimatedCost == null) continue;
+		accumulator.estimatedCost += group.estimatedCost;
+		accumulator.hasEstimatedCost = true;
+		if (group.costUnit) accumulator.costUnits.add(group.costUnit.toLowerCase());
+		else accumulator.hasUnknownCostUnit = true;
+	}
+}
+function summarizeUsage(accumulators) {
+	const summaries = /* @__PURE__ */ new Map();
+	for (const [traceId, accumulator] of accumulators) {
+		const summary = {
+			inputTokens: accumulator.inputTokens,
+			outputTokens: accumulator.outputTokens
+		};
+		if (accumulator.hasEstimatedCost && !accumulator.hasUnknownCostUnit && accumulator.costUnits.size === 1) {
+			summary.estimatedCost = accumulator.estimatedCost;
+			summary.costUnit = [...accumulator.costUnits][0];
+		}
+		summaries.set(traceId, summary);
+	}
+	return summaries;
+}
+function useTraceUsage({ traceIds, enabled, autoRefetch, queryOptions }) {
+	const client = useMastraClient();
+	const uniqueTraceIds = [...new Set(traceIds)].toSorted();
+	const projectKey = `${client.options.baseUrl || (typeof window === "undefined" ? "local" : window.location.origin || "local")}:${client.options.apiPrefix ?? "/api"}`;
+	return useQuery({
+		queryKey: [
+			"trace-usage",
+			projectKey,
+			uniqueTraceIds
+		],
+		enabled: enabled && uniqueTraceIds.length > 0,
+		queryFn: async () => {
+			const batches = chunkTraceIds(uniqueTraceIds);
+			const responses = await Promise.allSettled(batches.map((batch) => client.getMetricBreakdown({
+				name: [INPUT_TOKEN_METRIC, OUTPUT_TOKEN_METRIC],
+				aggregation: "sum",
+				groupBy: ["traceId", "name"],
+				filters: { traceIds: batch },
+				limit: batch.length * 2
+			})));
+			const accumulators = /* @__PURE__ */ new Map();
+			for (const response of responses) if (response.status === "fulfilled") addBreakdown(accumulators, response.value);
+			return summarizeUsage(accumulators);
+		},
+		placeholderData: (previousData, previousQuery) => previousQuery?.queryKey[1] === projectKey ? previousData : void 0,
+		refetchInterval: enabled && autoRefetch ? 1e4 : false,
+		...queryOptions
+	});
+}
+//#endregion
+//#region src/hooks/traces/use-traces.tsx
+const deltaSupportByClient = /* @__PURE__ */ new WeakMap();
+const lightListSupportByClient = /* @__PURE__ */ new WeakMap();
+/** When the current run of light-endpoint 500s started, per client. Cleared by any light success. */
+const lightListFirstServerErrorAtByClient = /* @__PURE__ */ new WeakMap();
+/** A 500 is ambiguous — an old core's store throwing, or a transient fault (DB hiccup, timeout).
+*  Serve the request from the full endpoint either way, but only pin the session once the 500s
+*  have outlasted a blip; a hiccup would otherwise degrade the list until the tab is reloaded.
+*  Elapsed time, not a request count: the page refetch, the delta poll and the status refresh can
+*  fail in the same instant, and a fallback response still looks like a success to the delta query,
+*  so chase mode keeps re-polling every `deltaChaseIntervalMs` throughout the outage. */
+const LIGHT_LIST_SERVER_ERROR_PIN_AFTER_MS = 1e4;
+const DEFAULT_POLLING_CONFIG = {
+	deltaPollIntervalMs: 5e3,
+	deltaChaseIntervalMs: 100,
+	deltaLimit: 100,
+	pageModeRefetchIntervalMs: 1e4,
+	page0StatusRefreshIntervalMs: 6e4,
+	idleGuardThresholdMs: 15 * 6e4,
+	minRefetchSpinMs: 400,
+	deltaHighlightMs: 1e3
+};
+/** Returns true when the cursor should be considered stale and re-seeded.
+*  Exported for testing — pure function of timestamps. */
+function shouldResetAfterIdle(lastSuccessAt, now, thresholdMs) {
+	if (lastSuccessAt === 0) return false;
+	return now - lastSuccessAt > thresholdMs;
+}
+function isHttp501(error) {
+	return error?.status === 501;
+}
+/** Only 404 and 500 can mean the light endpoint isn't served: 404 from servers without
+*  the route, 500 from cores whose store throws instead of serving the projection.
+*  Anything else (401, 403, 429, other 5xx, the 501 disabled-domain signal) is a
+*  condition the full endpoint would hit too, so it propagates instead of falling
+*  back — mirroring how the delta-support cache matches exactly 501. */
+function lightListFallbackStatus(error) {
+	const status = error?.status;
+	return status === 404 || status === 500 ? status : void 0;
+}
+/** Whether a failed light-list request should pin the session to the full endpoint.
+*  `firstServerErrorAt` is undefined when this 500 opens a new run of them, so a single
+*  fault never pins. Exported for testing — pure function of the status and timestamps. */
+function shouldPinLightList(status, firstServerErrorAt, now) {
+	if (status === 404) return true;
+	if (status !== 500) return false;
+	if (firstServerErrorAt === void 0) return false;
+	return now - firstServerErrorAt >= LIGHT_LIST_SERVER_ERROR_PIN_AFTER_MS;
+}
+const fetchTracesFn = async (args) => {
+	const { client, filters, listMode = "traces" } = args;
+	const params = args.mode === "delta" ? {
+		mode: "delta",
+		after: args.after,
+		limit: args.limit,
+		filters
+	} : {
+		pagination: {
+			page: args.page,
+			perPage: args.perPage
+		},
+		filters
+	};
+	if (listMode === "branches") return client.listBranches(params);
+	if (lightListSupportByClient.get(client) === "unsupported") return client.listTraces(params);
+	try {
+		const response = await client.listTracesLight(params);
+		if (args.mode !== "delta") {
+			const spans = response.spans ?? [];
+			if (spans.length > 0 && spans.every((span) => span.status === void 0)) {
+				lightListSupportByClient.set(client, "unsupported");
+				return client.listTraces(params);
+			}
+		}
+		lightListFirstServerErrorAtByClient.delete(client);
+		return response;
+	} catch (error) {
+		const status = lightListFallbackStatus(error);
+		if (status === void 0) throw error;
+		const now = Date.now();
+		const firstServerErrorAt = lightListFirstServerErrorAtByClient.get(client);
+		if (status === 500 && firstServerErrorAt === void 0) lightListFirstServerErrorAtByClient.set(client, now);
+		if (shouldPinLightList(status, firstServerErrorAt, now)) lightListSupportByClient.set(client, "unsupported");
+		return client.listTraces(params);
+	}
+};
+const TRACES_PER_PAGE = 25;
+/** Returns the next page number if the server indicates more pages are available. */
+function getTracesNextPageParam(lastPage, _allPages, lastPageParam) {
+	if (lastPage?.pagination?.hasMore) return lastPageParam + 1;
+}
+/** Branch rows are full spans and trace rows are lightweight; the list only reads the
+*  fields they share, so both are surfaced as `LightSpanRecord`. */
+function getPageSpans(page) {
+	if ("branches" in page) return page.branches ?? [];
+	return page.spans ?? [];
+}
+/** Deduplicates trace/branch rows by traceId + spanId across all loaded pages.
+*  Also surfaces page 0's deltaCursor so the live-tail query can read it reactively. */
+function selectUniqueTraces(data) {
+	const seen = /* @__PURE__ */ new Set();
+	return {
+		spans: data.pages.flatMap((page) => getPageSpans(page)).filter((span) => {
+			const key = `${span.traceId}:${span.spanId}`;
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		}),
+		deltaCursor: data.pages[0]?.deltaCursor
+	};
+}
+function rowKey(row) {
+	return `${row.traceId}:${row.spanId}`;
+}
+function indexRowsByKey(rows) {
+	return new Map(rows.map((row) => [rowKey(row), row]));
+}
+/** Replaces existing page-0 rows in place (keyed by traceId:spanId) with
+*  refreshed copies from the server. Rows the server doesn't return are kept
+*  as-is so delta-accumulated rows that have aged off the server's page 0
+*  aren't dropped from the UI. New rows aren't added here — delta polling
+*  delivers those. */
+function refreshPage0Rows(old, refreshed, listMode) {
+	if (!old || old.pages.length === 0) return old;
+	const [firstPage, ...rest] = old.pages;
+	if (!firstPage) return old;
+	let updatedFirst;
+	if (listMode === "branches" && "branches" in firstPage && "branches" in refreshed) {
+		const refreshedByKey = indexRowsByKey(refreshed.branches ?? []);
+		if (refreshedByKey.size === 0) return old;
+		updatedFirst = {
+			...firstPage,
+			branches: (firstPage.branches ?? []).map((existing) => refreshedByKey.get(rowKey(existing)) ?? existing)
+		};
+	} else if ("spans" in firstPage && "spans" in refreshed) {
+		const refreshedByKey = indexRowsByKey(refreshed.spans ?? []);
+		if (refreshedByKey.size === 0) return old;
+		updatedFirst = {
+			...firstPage,
+			spans: (firstPage.spans ?? []).map((existing) => refreshedByKey.get(rowKey(existing)) ?? existing)
+		};
+	} else return old;
+	return {
+		...old,
+		pages: [updatedFirst, ...rest]
+	};
+}
+/** Stable `startedAt DESC` sort matching the server's default page-mode
+*  ordering for both list endpoints. Rows missing `startedAt` sink to the
+*  bottom (compared as time 0). */
+function sortRowsByStartedAtDesc(rows) {
+	return [...rows].sort((a, b) => {
+		const aTime = a.startedAt ? new Date(a.startedAt).getTime() : 0;
+		return (b.startedAt ? new Date(b.startedAt).getTime() : 0) - aTime;
+	});
+}
+/** Prepends delta-mode rows into page 0 and advances its deltaCursor.
+*  Delta responses come back in server cursor order (insertion order into
+*  the per-store delta index), not the `startedAt DESC` order page-mode
+*  uses — so we re-sort the merged page 0 to match what the user sees on
+*  a fresh page-mode load. Cross-page duplication is handled later by
+*  selectUniqueTraces. */
+function mergeDeltaIntoPage0(old, delta, listMode) {
+	if (!old || old.pages.length === 0) return old;
+	const [firstPage, ...rest] = old.pages;
+	if (!firstPage) return old;
+	const nextCursor = delta.deltaCursor ?? firstPage.deltaCursor;
+	let updatedFirst;
+	if (listMode === "branches" && "branches" in firstPage) {
+		const newRows = delta.branches ?? [];
+		updatedFirst = {
+			...firstPage,
+			branches: sortRowsByStartedAtDesc([...newRows, ...firstPage.branches ?? []]),
+			deltaCursor: nextCursor
+		};
+	} else if ("spans" in firstPage) {
+		const newRows = delta.spans ?? [];
+		updatedFirst = {
+			...firstPage,
+			spans: sortRowsByStartedAtDesc([...newRows, ...firstPage.spans ?? []]),
+			deltaCursor: nextCursor
+		};
+	} else return old;
+	return {
+		...old,
+		pages: [updatedFirst, ...rest]
+	};
+}
+const useTraces = ({ filters, listMode = "traces", polling = {}, enabled = true, queryOptions }) => {
+	const { deltaPollIntervalMs = DEFAULT_POLLING_CONFIG.deltaPollIntervalMs, deltaChaseIntervalMs = DEFAULT_POLLING_CONFIG.deltaChaseIntervalMs, deltaLimit = DEFAULT_POLLING_CONFIG.deltaLimit, pageModeRefetchIntervalMs = DEFAULT_POLLING_CONFIG.pageModeRefetchIntervalMs, page0StatusRefreshIntervalMs = DEFAULT_POLLING_CONFIG.page0StatusRefreshIntervalMs, idleGuardThresholdMs = DEFAULT_POLLING_CONFIG.idleGuardThresholdMs, minRefetchSpinMs = DEFAULT_POLLING_CONFIG.minRefetchSpinMs, deltaHighlightMs = DEFAULT_POLLING_CONFIG.deltaHighlightMs } = polling;
+	const client = useMastraClient();
+	const queryClient = useQueryClient();
+	const { inView: isEndOfListInView, setRef: setEndOfListElement } = useInView();
+	const [deltaSupport, setDeltaSupport] = useState(() => deltaSupportByClient.get(client) ?? "unknown");
+	const deltaUnsupported = deltaSupport === "unsupported";
+	const [autoRefetch, setAutoRefetch] = useState(true);
+	const [recentlyAddedKeys, setRecentlyAddedKeys] = useState(() => /* @__PURE__ */ new Set());
+	useEffect(() => {
+		setRecentlyAddedKeys(/* @__PURE__ */ new Set());
+	}, [listMode, filters]);
+	const tracesQueryKey = [
+		"traces",
+		listMode,
+		filters
+	];
+	const query = useInfiniteQuery({
+		queryKey: tracesQueryKey,
+		enabled,
+		queryFn: ({ pageParam }) => fetchTracesFn({
+			client,
+			page: pageParam,
+			perPage: 25,
+			filters,
+			listMode
+		}),
+		initialPageParam: 0,
+		getNextPageParam: getTracesNextPageParam,
+		select: selectUniqueTraces,
+		retry: false,
+		refetchInterval: (q) => {
+			if (is403ForbiddenError(q.state.error)) return false;
+			if (!autoRefetch) return false;
+			return deltaUnsupported ? pageModeRefetchIntervalMs : false;
+		},
+		...queryOptions?.traces
+	});
+	const cursor = query.data?.deltaCursor;
+	useEffect(() => {
+		if (query.isSuccess && cursor === void 0 && deltaSupport === "unknown") {
+			deltaSupportByClient.set(client, "unsupported");
+			setDeltaSupport("unsupported");
+		}
+	}, [
+		query.isSuccess,
+		cursor,
+		deltaSupport,
+		client
+	]);
+	const deltaQuery = useQuery({
+		queryKey: [
+			"traces-delta",
+			listMode,
+			filters
+		],
+		queryFn: () => {
+			const current = queryClient.getQueryData(tracesQueryKey)?.pages[0]?.deltaCursor;
+			if (!current) return null;
+			return fetchTracesFn({
+				client,
+				mode: "delta",
+				after: current,
+				limit: deltaLimit,
+				filters,
+				listMode
+			});
+		},
+		enabled: enabled && !!cursor && !deltaUnsupported && autoRefetch,
+		retry: false,
+		refetchInterval: (q) => {
+			if (q.state.error) return false;
+			if (q.state.data?.delta?.hasMore) return deltaChaseIntervalMs;
+			return deltaPollIntervalMs;
+		},
+		...queryOptions?.delta
+	});
+	useEffect(() => {
+		const result = deltaQuery.data;
+		if (!result) return;
+		queryClient.setQueryData(tracesQueryKey, (old) => mergeDeltaIntoPage0(old, result, listMode));
+		const newRows = listMode === "branches" && "branches" in result ? result.branches ?? [] : "spans" in result ? result.spans ?? [] : [];
+		if (newRows.length === 0) return;
+		const keys = newRows.map((r) => `${r.traceId}:${r.spanId ?? ""}`);
+		setRecentlyAddedKeys((prev) => {
+			const next = new Set(prev);
+			for (const k of keys) next.add(k);
+			return next;
+		});
+		setTimeout(() => {
+			setRecentlyAddedKeys((prev) => {
+				const next = new Set(prev);
+				for (const k of keys) next.delete(k);
+				return next;
+			});
+		}, deltaHighlightMs);
+	}, [
+		deltaQuery.data,
+		queryClient,
+		listMode,
+		filters,
+		deltaHighlightMs
+	]);
+	useEffect(() => {
+		if (isHttp501(deltaQuery.error)) {
+			deltaSupportByClient.set(client, "unsupported");
+			setDeltaSupport("unsupported");
+		}
+	}, [deltaQuery.error, client]);
+	const statusRefreshQuery = useQuery({
+		queryKey: [
+			"traces-status-refresh",
+			listMode,
+			filters
+		],
+		queryFn: () => fetchTracesFn({
+			client,
+			page: 0,
+			perPage: 25,
+			filters,
+			listMode
+		}),
+		enabled: enabled && !!cursor && !deltaUnsupported && autoRefetch,
+		refetchInterval: page0StatusRefreshIntervalMs,
+		refetchOnMount: false,
+		retry: false,
+		...queryOptions?.statusRefresh
+	});
+	useEffect(() => {
+		const result = statusRefreshQuery.data;
+		if (!result) return;
+		queryClient.setQueryData(tracesQueryKey, (old) => refreshPage0Rows(old, result, listMode));
+	}, [
+		statusRefreshQuery.data,
+		queryClient,
+		listMode,
+		filters
+	]);
+	const lastSuccessAtRef = useRef(0);
+	useEffect(() => {
+		const ts = Math.max(query.dataUpdatedAt, deltaQuery.dataUpdatedAt, statusRefreshQuery.dataUpdatedAt);
+		if (ts > lastSuccessAtRef.current) lastSuccessAtRef.current = ts;
+	}, [
+		query.dataUpdatedAt,
+		deltaQuery.dataUpdatedAt,
+		statusRefreshQuery.dataUpdatedAt
+	]);
+	const autoRefetchRef = useRef(autoRefetch);
+	useEffect(() => {
+		autoRefetchRef.current = enabled && autoRefetch;
+	}, [enabled, autoRefetch]);
+	useEffect(() => {
+		const handler = () => {
+			if (document.visibilityState !== "visible") return;
+			if (!autoRefetchRef.current) return;
+			if (!shouldResetAfterIdle(lastSuccessAtRef.current, Date.now(), idleGuardThresholdMs)) return;
+			queryClient.resetQueries({ queryKey: [
+				"traces",
+				listMode,
+				filters
+			] });
+		};
+		document.addEventListener("visibilitychange", handler);
+		return () => document.removeEventListener("visibilitychange", handler);
+	}, [
+		queryClient,
+		listMode,
+		filters,
+		idleGuardThresholdMs
+	]);
+	const { hasNextPage, isFetchingNextPage, fetchNextPage } = query;
+	useEffect(() => {
+		if (enabled && isEndOfListInView && hasNextPage && !isFetchingNextPage) fetchNextPage();
+	}, [
+		enabled,
+		isEndOfListInView,
+		hasNextPage,
+		isFetchingNextPage,
+		fetchNextPage
+	]);
+	const isFetchingAny = query.isFetching || statusRefreshQuery.isFetching || deltaQuery.isFetching;
+	const lastActivityAt = Math.max(query.dataUpdatedAt, query.errorUpdatedAt, deltaQuery.dataUpdatedAt, deltaQuery.errorUpdatedAt, statusRefreshQuery.dataUpdatedAt, statusRefreshQuery.errorUpdatedAt);
+	const [pulse, setPulse] = useState(false);
+	const prevActivityAtRef = useRef(lastActivityAt);
+	useEffect(() => {
+		if (lastActivityAt > prevActivityAtRef.current) {
+			prevActivityAtRef.current = lastActivityAt;
+			setPulse(true);
+			const t = setTimeout(() => setPulse(false), minRefetchSpinMs);
+			return () => clearTimeout(t);
+		}
+	}, [lastActivityAt, minRefetchSpinMs]);
+	const isRefetching = isFetchingAny || pulse;
+	return {
+		...query,
+		setEndOfListElement,
+		isRefetching,
+		autoRefetch,
+		setAutoRefetch,
+		recentlyAddedKeys
+	};
+};
+//#endregion
+//#region src/hooks/traces/use-create-feedback.tsx
+/**
+* Submits a free-text comment as a feedback record, scoped to the trace or to a
+* single span, then invalidates the matching feedback list so it refreshes.
+*/
+const useCreateFeedback = ({ traceId, spanId, queryOptions }) => {
+	const client = useMastraClient();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: ({ text }) => client.createFeedback({ feedback: {
+			traceId,
+			...spanId ? { spanId } : {},
+			feedbackType: "comment",
+			feedbackSource: "user",
+			value: text
+		} }),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: spanId ? [
+			"span-feedback",
+			traceId,
+			spanId
+		] : ["trace-feedback", traceId] }),
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-delete-feedback.tsx
+/**
+* Deletes a single feedback record by id, then invalidates the matching
+* feedback list (trace- or span-scoped) so it refreshes.
+*/
+const useDeleteFeedback = ({ traceId, spanId, queryOptions }) => {
+	const client = useMastraClient();
+	const queryClient = useQueryClient();
+	return useMutation({
+		mutationFn: ({ feedbackId }) => client.deleteFeedback({ feedbackIds: [feedbackId] }),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: spanId ? [
+			"span-feedback",
+			traceId,
+			spanId
+		] : ["trace-feedback", traceId] }),
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-span-feedback.tsx
+/**
+* Feedback scoped to a single span. Both identifiers are required: without a `spanId`
+* the query stays disabled rather than falling back to trace-wide feedback.
+*
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+const useSpanFeedback = ({ traceId = "", spanId = "", page, queryOptions }) => {
+	const client = useMastraClient();
+	const pageNumber = page ?? 0;
+	return useQuery({
+		queryKey: [
+			"span-feedback",
+			traceId,
+			spanId,
+			pageNumber
+		],
+		queryFn: () => client.listFeedback({
+			filters: {
+				traceId,
+				spanId
+			},
+			pagination: {
+				page: pageNumber,
+				perPage: 10
+			}
+		}),
+		refetchInterval: getFeedbackRefetchInterval,
+		gcTime: 0,
+		staleTime: 0,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-trace-feedback.tsx
+/** Loads a page of trace-level feedback and stops polling when storage cannot serve feedback. */
+/**
+* Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+*/
+const useTraceFeedback = ({ traceId = "", page, queryOptions }) => {
+	const client = useMastraClient();
+	const pageNumber = page ?? 0;
+	return useQuery({
+		queryKey: [
+			"trace-feedback",
+			traceId,
+			pageNumber
+		],
+		queryFn: () => client.listFeedback({
+			filters: { traceId },
+			pagination: {
+				page: pageNumber,
+				perPage: 10
+			}
+		}),
+		select: (data) => {
+			const feedback = data.feedback.filter((item) => !item.spanId);
+			if (!data.pagination) return {
+				...data,
+				feedback
+			};
+			return {
+				...data,
+				feedback,
+				pagination: {
+					...data.pagination,
+					total: feedback.length
+				}
+			};
+		},
+		refetchInterval: getFeedbackRefetchInterval,
+		gcTime: 0,
+		staleTime: 0,
+		...queryOptions
+	});
+};
+//#endregion
+//#region src/hooks/traces/use-trace-metadata-filter-fields.ts
+const DISCOVERY_LIMIT = 100;
+const EMPTY_FIELDS = {
+	canonicalFields: [],
+	observedFields: [],
+	observedFieldsTruncated: false
+};
+const TRACE_QUERY_DISCOVERY_UNSUPPORTED = "TRACE_QUERY_DISCOVERY_UNSUPPORTED";
+const isDiscoveryUnsupportedError = (error) => error instanceof MastraClientError && typeof error.body === "object" && error.body !== null && error.body.code === TRACE_QUERY_DISCOVERY_UNSUPPORTED;
+const traceQueryFieldsQueryKey = (timeRange) => [
+	"trace-query-fields",
+	timeRange.from,
+	timeRange.to
+];
+/** Lazy FilterBar suggestions resolver backed by the value-discovery endpoint for one
+*  `predicateScope` + `path`. the caller owns debounce/abort; this only fetches. */
+const createTraceQueryValuesResolver = (client, timeRange, predicateScope, path) => {
+	return async ({ query: search, signal }) => {
+		const { values } = await client.getTraceQueryValues({
+			timeRange,
+			predicateScope,
+			path,
+			search: search.trim() || void 0,
+			limit: DISCOVERY_LIMIT
+		}, { signal });
+		return values.map(({ value }) => ({ value }));
+	};
+};
+/**
+* Discovers the `metadata.*` fields observed on traces in the given time range and returns
+* them as filter bar fields, each with a lazy `suggestions` resolver that fetches the field's
+* values when the user opens the value step (the caller owns debounce/abort).
+*
+* Resolves to an empty field list when the server or store does not support discovery
+* (`TRACE_QUERY_DISCOVERY_UNSUPPORTED`) so callers never stay blocked.
+*/
+const useTraceMetadataFilterFields = ({ timeRange, queryOptions }) => {
+	const client = useMastraClient();
+	const query = useQuery({
+		queryKey: traceQueryFieldsQueryKey(timeRange),
+		queryFn: async ({ signal }) => {
+			try {
+				return await client.getTraceQueryFields({
+					timeRange,
+					predicateScope: "trace",
+					limit: DISCOVERY_LIMIT
+				}, { signal });
+			} catch (error) {
+				if (isDiscoveryUnsupportedError(error)) return EMPTY_FIELDS;
+				throw error;
+			}
+		},
+		retry: false,
+		staleTime: DISCOVERY_STALE_TIME,
+		placeholderData: keepPreviousData,
+		...queryOptions
+	});
+	const observedFields = query.data?.observedFields;
+	return {
+		fields: useMemo(() => (observedFields ?? []).map((field) => ({
+			path: field.path,
+			suggestions: createTraceQueryValuesResolver(client, timeRange, "trace", field.path)
+		})), [
+			observedFields,
+			client,
+			timeRange
+		]),
+		isLoading: query.isLoading,
+		error: query.error
+	};
+};
+//#endregion
+//#region src/hooks/traces/use-trace-column-preferences-storage-key.ts
+/**
+* Storage key for the trace list column preferences, scoped to the Mastra server the client
+* talks to so each project keeps its own column layout.
+*/
+function useTraceColumnPreferencesStorageKey() {
+	const client = useMastraClient();
+	return `mastra:traces:columns:${client.options.baseUrl || (typeof window === "undefined" ? "local" : window.location.origin || "local")}:${client.options.apiPrefix ?? "/api"}`;
+}
+//#endregion
+export { DISCOVERY_STALE_TIME, ROOT_ENTITY_TYPES, TRACES_PER_PAGE, TRACE_QUERY_PER_PAGE, createTraceQueryValuesResolver, getLegacyTraceQueryNextPageParam, getTraceQueryNextPageParam, getTracesNextPageParam, lightSpanToTraceQueryTrace, mergeDeltaIntoPage0, refreshPage0Rows, selectLegacyTraceQueryTraces, selectTraceQueryTraces, selectUniqueTraces, shouldPinLightList, shouldResetAfterIdle, traceQueryFieldsQueryKey, traceSpansQueryOptions, useBranch, useCreateFeedback, useDeleteFeedback, useEntityNames, useEnvironments, useFetchTraceSpans, useServiceNames, useSpanDetail, useSpanFeedback, useTags, useThreadHasOtherTraces, useTraceColumnPreferencesStorageKey, useTraceFeedback, useTraceLightSpans, useTraceMetadataFilterFields, useTraceOrBranchSpans, useTraceQuery, useTraceSpans, useTraceSpansQueries, useTraceUsage, useTraces };
+
+//# sourceMappingURL=index.js.map