@mastra/react 0.0.0-studio-cli-20260504022012 → 0.0.0-sugared-octave-20261030170102

package/dist/hooks/traces/use-thread-has-other-traces.d.ts

@@ -0,0 +1,17 @@
+import type { MastraClient } from '@mastra/client-js';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+/**
+ * Whether the memory thread holds more than one trace, i.e. whether a "full thread" view would
+ * show anything beyond the current turn. `false` while loading or on error, so the link only
+ * appears once we know it leads somewhere.
+ */
+type ThreadTracesResponse = Awaited<ReturnType<MastraClient['listTracesLight']>>;
+/**
+ * Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+ */
+export declare function useThreadHasOtherTraces({ threadId, queryOptions, }: {
+    threadId: string | undefined;
+    queryOptions?: MastraQueryOptions<ThreadTracesResponse, boolean>;
+}): boolean;
+export {};
+//# sourceMappingURL=use-thread-has-other-traces.d.ts.map

package/dist/hooks/traces/use-thread-has-other-traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-thread-has-other-traces.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-thread-has-other-traces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;GAIG;AACH,KAAK,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAEjF;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,QAAQ,EACR,YAAY,GACb,EAAE;IACD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,YAAY,CAAC,EAAE,kBAAkB,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;CAClE,GAAG,OAAO,CAeV"}

package/dist/hooks/traces/use-trace-aggregate.d.ts

@@ -0,0 +1,17 @@
+import type { AggregateTracesArgs, AggregateTracesResponse } from '@mastra/client-js';
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+export interface UseTraceAggregateArgs<TData = AggregateTracesResponse> {
+    request: AggregateTracesArgs;
+    enabled?: boolean;
+    queryOptions?: MastraQueryOptions<AggregateTracesResponse, TData>;
+}
+/**
+ * Runs `aggregateTraces()` for `request`. Check `useTraceAggregateAvailable()` before enabling it.
+ *
+ * It doesn't poll: grouped requests over large tenants take seconds, so it refetches only when the
+ * request changes or the caller calls `refetch()`. The client already retries server errors, so
+ * React Query doesn't retry on top of it, and a rejected request (4xx) fails once.
+ */
+export declare function useTraceAggregate<TData = AggregateTracesResponse>({ request, enabled, queryOptions, }: UseTraceAggregateArgs<TData>): UseQueryResult<TData, Error>;
+//# sourceMappingURL=use-trace-aggregate.d.ts.map

package/dist/hooks/traces/use-trace-aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-aggregate.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,WAAW,qBAAqB,CAAC,KAAK,GAAG,uBAAuB;IACpE,OAAO,EAAE,mBAAmB,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;CACnE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,uBAAuB,EAAE,EACjE,OAAO,EACP,OAAc,EACd,YAAY,GACb,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAU7D"}

package/dist/hooks/traces/use-trace-column-preferences-storage-key.d.ts

@@ -0,0 +1,8 @@
+export type TraceColumnPreferencesScope = 'traces' | 'spans' | 'threads';
+/**
+ * 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, and to the list (traces, spans or threads)
+ * so each list keeps its own selection.
+ */
+export declare function useTraceColumnPreferencesStorageKey(scope?: TraceColumnPreferencesScope): string;
+//# sourceMappingURL=use-trace-column-preferences-storage-key.d.ts.map

package/dist/hooks/traces/use-trace-column-preferences-storage-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-column-preferences-storage-key.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-column-preferences-storage-key.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,GAAE,2BAAsC,GAAG,MAAM,CAMzG"}

package/dist/hooks/traces/use-trace-feedback.d.ts

@@ -0,0 +1,16 @@
+import type { MastraClient } from '@mastra/client-js';
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+type TraceFeedbackResponse = Awaited<ReturnType<MastraClient['listFeedback']>>;
+type UseTraceFeedbackProps<TData> = {
+    traceId?: string;
+    page?: number;
+    queryOptions?: MastraQueryOptions<TraceFeedbackResponse, TData>;
+};
+/** 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.
+ */
+export declare const useTraceFeedback: <TData = TraceFeedbackResponse>({ traceId, page, queryOptions, }: UseTraceFeedbackProps<TData>) => UseQueryResult<TData, Error>;
+export {};
+//# sourceMappingURL=use-trace-feedback.d.ts.map

package/dist/hooks/traces/use-trace-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-feedback.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-feedback.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,KAAK,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;AAE/E,KAAK,qBAAqB,CAAC,KAAK,IAAI;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,kBAAkB,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC;CACjE,CAAC;AAEF,iGAAiG;AACjG;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,GAAG,qBAAqB,oCAI3D,qBAAqB,CAAC,KAAK,CAAC,KAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAsB5D,CAAC"}

package/dist/hooks/traces/use-trace-light-spans.d.ts

@@ -0,0 +1,16 @@
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+import type { LightSpanRecord } from './types.js';
+type TraceLightSpansResponse = {
+    traceId: string;
+    spans: LightSpanRecord[];
+} | null;
+/**
+ * Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+ */
+export declare function useTraceLightSpans<TData = TraceLightSpansResponse>({ traceId, queryOptions, }: {
+    traceId: string | null | undefined;
+    queryOptions?: MastraQueryOptions<TraceLightSpansResponse, TData>;
+}): UseQueryResult<TData, Error>;
+export {};
+//# sourceMappingURL=use-trace-light-spans.d.ts.map

package/dist/hooks/traces/use-trace-light-spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-light-spans.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-light-spans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,KAAK,uBAAuB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC;AAEpF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAG,uBAAuB,EAAE,EAClE,OAAO,EACP,YAAY,GACb,EAAE;IACD,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,YAAY,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;CACnE,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAyB/B"}

package/dist/hooks/traces/use-trace-metadata-filter-fields.d.ts

@@ -0,0 +1,42 @@
+import type { GetTraceQueryFieldsArgs, GetTraceQueryFieldsResponse, GetTraceQueryValuesArgs, MastraClient } from '@mastra/client-js';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+export type TraceQueryDiscoveryTimeRange = GetTraceQueryFieldsArgs['timeRange'];
+/** Lazy value lookup for one discovered field. Structurally compatible with filter bar suggestion resolvers. */
+export type TraceQueryValuesResolver = (ctx: {
+    query: string;
+    signal: AbortSignal;
+}) => Promise<{
+    value: string;
+}[]>;
+export type TraceMetadataFilterField = {
+    /** `metadata.<key>` — doubles as the filter bar field id. */
+    path: string;
+    suggestions: TraceQueryValuesResolver;
+};
+export declare const traceQueryFieldsQueryKey: (timeRange: TraceQueryDiscoveryTimeRange) => readonly ['trace-query-fields', string, string];
+/** Lazy FilterBar suggestions resolver backed by the value-discovery endpoint for one
+ *  `predicateScope` + `path`. the caller owns debounce/abort; this only fetches. */
+export declare const createTraceQueryValuesResolver: (client: MastraClient, timeRange: TraceQueryDiscoveryTimeRange, predicateScope: GetTraceQueryValuesArgs['predicateScope'], path: string) => TraceQueryValuesResolver;
+/**
+ * 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.
+ */
+export declare const useTraceMetadataFilterFields: ({ timeRange, queryOptions, }: {
+    timeRange: TraceQueryDiscoveryTimeRange;
+    queryOptions?: MastraQueryOptions<GetTraceQueryFieldsResponse>;
+}) => {
+    fields: TraceMetadataFilterField[];
+    canonicalFields: {
+        path: string;
+        valueKind: 'string' | 'number' | 'stringOrNumber' | 'timestamp' | 'presence' | 'array';
+        operators: ("eq" | "exists" | "gt" | "gte" | "in" | "includes" | "lt" | "lte" | "matches" | "ne" | "notExists" | "notIn" | "notIncludes" | "notMatches")[];
+        valueSuggestions: boolean;
+    }[];
+    isLoading: boolean;
+    error: Error | null;
+};
+//# sourceMappingURL=use-trace-metadata-filter-fields.d.ts.map

package/dist/hooks/traces/use-trace-metadata-filter-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-metadata-filter-fields.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-metadata-filter-fields.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,MAAM,MAAM,4BAA4B,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;AAEhF,gHAAgH;AAChH,MAAM,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAAC;AAErH,MAAM,MAAM,wBAAwB,GAAG;IACrC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,wBAAwB,CAAC;CACvC,CAAC;AAmBF,eAAO,MAAM,wBAAwB,cAAe,4BAA4B,eAC7E,oBAAoB,iBAAwC,CAAC;AAEhE;oFACoF;AACpF,eAAO,MAAM,8BAA8B,WACjC,YAAY,aACT,4BAA4B,kBACvB,uBAAuB,CAAC,gBAAgB,CAAC,QACnD,MAAM,KACX,wBAQF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,iCAGtC;IACD,SAAS,EAAE,4BAA4B,CAAC;IACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,2BAA2B,CAAC,CAAC;CAChE;;;;;;;;;;CAqCA,CAAC"}

package/dist/hooks/traces/use-trace-or-branch-spans.d.ts

@@ -0,0 +1,39 @@
+import type { MastraQueryOptions } from '../shared/query-options.js';
+import type { TraceListMode, LightSpanRecord } from './types.js';
+import type { BranchResponse } from './use-branch.js';
+import type { TraceSpansData } from './use-trace-spans.js';
+export interface UseTraceOrBranchSpansArgs {
+    traceId: string | null | undefined;
+    /** Required when `listMode === 'branches'` — the anchor span identifying the displayed
+     *  subtree. The hook fetches `getBranch(traceId, anchorSpanId)`. Intra-panel span selection
+     *  is separate (the caller's `spanIdParam`); the anchor stays put while it changes. */
+    anchorSpanId?: string | null;
+    listMode: TraceListMode;
+    depth?: number;
+    /**
+     * Per-query TanStack overrides, spread last. `select` must keep the default data shape
+     * because this hook reads `.spans` from both results.
+     */
+    queryOptions?: {
+        trace?: MastraQueryOptions<TraceSpansData, TraceSpansData, (string | null | undefined)[]>;
+        branch?: MastraQueryOptions<BranchResponse, BranchResponse>;
+    };
+}
+export interface UseTraceOrBranchSpansResult {
+    spans: LightSpanRecord[] | undefined;
+    /** Set in branches mode; undefined in traces mode (which uses parentSpanId == null). */
+    anchorSpanId: string | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: unknown;
+}
+/**
+ * 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.
+ */
+export declare function useTraceOrBranchSpans({ traceId, anchorSpanId, listMode, depth, queryOptions, }: UseTraceOrBranchSpansArgs): UseTraceOrBranchSpansResult;
+//# sourceMappingURL=use-trace-or-branch-spans.d.ts.map

package/dist/hooks/traces/use-trace-or-branch-spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-or-branch-spans.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-or-branch-spans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC;;2FAEuF;IACvF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,kBAAkB,CAAC,cAAc,EAAE,cAAc,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1F,MAAM,CAAC,EAAE,kBAAkB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;KAC7D,CAAC;CACH;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACrC,wFAAwF;IACxF,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,KAAK,EACL,YAAY,GACb,EAAE,yBAAyB,GAAG,2BAA2B,CA+BzD"}

package/dist/hooks/traces/use-trace-query.d.ts

@@ -0,0 +1,106 @@
+import { MastraClient } from '@mastra/client-js';
+import type { QueryTracesKeysetInput, TraceQueryKeysetTraceResponse } from '@mastra/client-js';
+import type { ListTracesArgs as StorageListTracesArgs } from '@mastra/core/storage';
+import type { InfiniteData } from '@tanstack/react-query';
+import type { MastraInfiniteQueryOptions, MastraQueryOptions } from '../shared/query-options.js';
+export declare const TRACE_QUERY_PER_PAGE = 25;
+/** Max traces per delta request; the server caps `limit` at 100. */
+export declare const TRACE_QUERY_DELTA_LIMIT = 100;
+type TraceQueryTrace = TraceQueryKeysetTraceResponse['traces'][number];
+type LegacyTraceListFilters = StorageListTracesArgs['filters'];
+type ListTracesLightResponse = Awaited<ReturnType<MastraClient['listTracesLight']>>;
+type LightSpanRecord = ListTracesLightResponse['spans'][number];
+export type TraceQueryArgs = Omit<QueryTracesKeysetInput, 'page' | 'pagination'>;
+export interface UseTraceQueryArgs {
+    query: TraceQueryArgs | undefined;
+    limit?: number;
+    enabled?: boolean;
+    /** When false, lists traces through the legacy `listTracesLight` endpoint instead of the trace-query API. */
+    withQueryTrace?: boolean;
+    /** Filters for the legacy endpoint, as built by `buildTraceListFilters`. Only read when `withQueryTrace` is false. */
+    legacyFilters?: LegacyTraceListFilters;
+    /** TanStack options spread last into the trace-query (`traceQuery`) and legacy (`legacy`) infinite queries. */
+    queryOptions?: {
+        traceQuery?: MastraInfiniteQueryOptions<TraceQueryKeysetTraceResponse, TraceQueryTrace[], readonly unknown[], string | undefined>;
+        legacy?: MastraInfiniteQueryOptions<ListTracesLightResponse, TraceQueryTrace[], readonly unknown[], number>;
+    };
+}
+export interface UseTraceQueryReturn {
+    data: TraceQueryTrace[] | undefined;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: () => void;
+    isLoading: boolean;
+    /** The rows belong to the previous query key (e.g. another thread) while the new one loads. */
+    isPlaceholderData: boolean;
+    isFetching: boolean;
+    isRefetching: boolean;
+    fetchStatus: 'idle' | 'fetching' | 'paused';
+    isError: boolean;
+    error: Error | null;
+    refetch: () => void;
+    setEndOfListElement: (node: HTMLDivElement | null) => void;
+}
+export declare function getTraceQueryNextPageParam(lastPage: TraceQueryKeysetTraceResponse | undefined): string | undefined;
+export declare function selectTraceQueryTraces(data: {
+    pages: TraceQueryKeysetTraceResponse[];
+}): TraceQueryTrace[];
+/** 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. */
+export declare function lightSpanToTraceQueryTrace(span: LightSpanRecord): TraceQueryTrace;
+export declare function selectLegacyTraceQueryTraces(data: {
+    pages: ListTracesLightResponse[];
+}): TraceQueryTrace[];
+export declare function getLegacyTraceQueryNextPageParam(lastPage: ListTracesLightResponse): number | undefined;
+/** Cache key of `useTraceQuery`'s trace-query list. Pass the same `query` and `limit` to share it. */
+export declare const traceQueryKey: (query: TraceQueryArgs | undefined, limit?: number) => readonly ['trace-query', TraceQueryArgs | undefined, number];
+/**
+ * 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.
+ */
+export declare function mergeTraceQueryDelta(data: InfiniteData<TraceQueryKeysetTraceResponse>, traces: TraceQueryTrace[], orderBy?: TraceQueryArgs['orderBy']): InfiniteData<TraceQueryKeysetTraceResponse>;
+/** Queries traces with cursor pagination and viewport-driven loading. */
+export declare function useTraceQuery({ query, limit, enabled, withQueryTrace, legacyFilters, queryOptions, }: UseTraceQueryArgs): UseTraceQueryReturn;
+export interface TraceQueryLatestData {
+    /** Opaque server watermark; the next poll sends it back as `after`. */
+    deltaCursor: string;
+}
+export interface UseTraceQueryLatestArgs {
+    /** The same `query` passed to `useTraceQuery`. Its `timeRange` and `where` must stay identical across polls. */
+    query: TraceQueryArgs | undefined;
+    /** The same `limit` passed to `useTraceQuery`, so new traces land in its cache. */
+    limit?: number;
+    enabled?: boolean;
+    /** Polling interval in ms; `false` polls only on mount, focus, or `refetch`. */
+    refetchInterval?: number | false;
+    /** TanStack options spread last into the underlying `useQuery`. */
+    queryOptions?: MastraQueryOptions<TraceQueryLatestData>;
+}
+/**
+ * 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`.
+ */
+export declare function useTraceQueryLatest({ query, limit, enabled, refetchInterval, queryOptions, }: UseTraceQueryLatestArgs): import("@tanstack/react-query").UseQueryResult<TraceQueryLatestData, Error>;
+export {};
+//# sourceMappingURL=use-trace-query.d.ts.map

package/dist/hooks/traces/use-trace-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-query.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-query.ts"],"names":[],"mappings":"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"}

package/dist/hooks/traces/use-trace-spans.d.ts

@@ -0,0 +1,46 @@
+import type { MastraClient } from '@mastra/client-js';
+import type { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+/**
+ * Key, fetcher and stale policy of the `trace-spans` query. Every observer of this key must
+ * share these (rather than only the key) so one observer with a stricter `staleTime` does not
+ * refetch data another one considers fresh.
+ */
+type TraceResponse = Awaited<ReturnType<MastraClient['getTrace']>>;
+export declare const traceSpansQueryOptions: (client: MastraClient, traceId: string | null | undefined) => UseQueryOptions<TraceResponse, Error, TraceResponse, (string | null | undefined)[]>;
+/**
+ * Every span of a single trace, with its full payload.
+ *
+ * The lightweight projection exists to keep blob columns off the read path of a
+ * *list*, where the cost is paid once per trace on screen. A trace that is open
+ * has already narrowed that to one, and the panel both renders and searches
+ * these spans -- `input`, `output` and `attributes` included -- so the
+ * projection would only hide content the reader is looking at.
+ */
+export type TraceSpansData = Awaited<ReturnType<MastraClient['getTrace']>>;
+/**
+ * Does not guard on empty ids; pass `queryOptions: { enabled }` to skip the fetch.
+ */
+export declare function useTraceSpans<TData = TraceSpansData>({ traceId, passive, queryOptions, }: {
+    traceId: string | null | undefined;
+    passive?: boolean;
+    queryOptions?: MastraQueryOptions<TraceSpansData, TData, (string | null | undefined)[]>;
+}): UseQueryResult<TData>;
+/**
+ * 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.
+ */
+export declare function useFetchTraceSpans(): (traceId: string) => Promise<TraceSpansData>;
+/**
+ * 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`.
+ */
+export declare function useTraceSpansQueries<T>({ traceIds, select, fallback, queryOptions, }: {
+    traceIds: string[];
+    select: (traceId: string, data: TraceSpansData) => T;
+    fallback: (traceId: string) => T;
+    /** Applied to every per-trace query. */
+    queryOptions?: MastraQueryOptions<TraceSpansData, T, (string | null | undefined)[]>;
+}): T[];
+export {};
+//# sourceMappingURL=use-trace-spans.d.ts.map

package/dist/hooks/traces/use-trace-spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-spans.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-spans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;GAIG;AACH,KAAK,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAEnE,eAAO,MAAM,sBAAsB,WACzB,YAAY,WACX,MAAM,GAAG,IAAI,GAAG,SAAS,KACjC,eAAe,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAYjF,CAAC;AAEL;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAE3E;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAG,cAAc,EAAE,EACpD,OAAO,EACP,OAAe,EACf,YAAY,GACb,EAAE;IACD,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,EAAE,KAAK,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;CACzF,GAAG,cAAc,CAAC,KAAK,CAAC,CAgBxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAKjF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EACtC,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,YAAY,GACb,EAAE;IACD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,KAAK,CAAC,CAAC;IACrD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,CAAC;IACjC,wCAAwC;IACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;CACrF,GAAG,CAAC,EAAE,CAiBN"}

package/dist/hooks/traces/use-trace-usage.d.ts

@@ -0,0 +1,10 @@
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { MastraQueryOptions } from '../shared/query-options.js';
+import type { TraceUsageSummary } from './types.js';
+export declare function useTraceUsage<TData = Map<string, TraceUsageSummary>>({ traceIds, enabled, autoRefetch, queryOptions, }: {
+    traceIds: readonly string[];
+    enabled: boolean;
+    autoRefetch: boolean;
+    queryOptions?: MastraQueryOptions<Map<string, TraceUsageSummary>, TData>;
+}): UseQueryResult<TData, Error>;
+//# sourceMappingURL=use-trace-usage.d.ts.map

package/dist/hooks/traces/use-trace-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-trace-usage.d.ts","sourceRoot":"","sources":["../../../src/hooks/traces/use-trace-usage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAwEjD,wBAAgB,aAAa,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,EACpE,QAAQ,EACR,OAAO,EACP,WAAW,EACX,YAAY,GACb,EAAE;IACD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,KAAK,CAAC,CAAC;CAC1E,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAqC/B"}

package/dist/hooks/traces/use-traces.d.ts

@@ -0,0 +1,244 @@
+import type { MastraClient } from '@mastra/client-js';
+import type { InfiniteData } from '@tanstack/react-query';
+import { useMastraClient } from '../../mastra-client-context.js';
+import type { MastraInfiniteQueryOptions, MastraQueryOptions } from '../shared/query-options.js';
+import type { TraceListMode } from './types.js';
+type ListBranchesArgs = NonNullable<Parameters<MastraClient['listBranches']>[0]>;
+type ListBranchesResponse = Awaited<ReturnType<MastraClient['listBranches']>>;
+type ListTracesArgs = NonNullable<Parameters<MastraClient['listTraces']>[0]>;
+type ListTracesLightResponse = Awaited<ReturnType<MastraClient['listTracesLight']>>;
+type LightSpanRecord = ListTracesLightResponse['spans'][number] | ListBranchesResponse['branches'][number];
+/** Tunables for live-tail polling. All fields optional — defaults below.
+ *  Platform consumers override individual fields to throttle traffic or
+ *  reshape the freshness/visibility trade-offs. */
+export interface TracesPollingConfig {
+    /** Interval between delta polls. Default 5_000ms. */
+    deltaPollIntervalMs?: number;
+    /** Refetch delay when the server signals `delta.hasMore` (chase remaining updates immediately). Default 100ms. */
+    deltaChaseIntervalMs?: number;
+    /** Max rows per delta poll. Server caps at 100. Default 100. */
+    deltaLimit?: number;
+    /** Page-mode refetch interval used when the configured store does not support delta polling. Default 10_000ms. */
+    pageModeRefetchIntervalMs?: number;
+    /** Periodic page-0 refetch interval while delta is active. Delta only delivers new rows, so this
+     *  is how we surface status flips (running → success/error) on rows already visible. Default 60_000ms. */
+    page0StatusRefreshIntervalMs?: number;
+    /** When the tab returns from being hidden and the last successful poll was older than this, the
+     *  cursor is treated as stale (ClickHouse delta tables TTL after 2 days; other stores may be more
+     *  aggressive). The infinite query is reset so page 0 refetches and delta resumes from a fresh
+     *  cursor. Default 900_000ms (15 min). */
+    idleGuardThresholdMs?: number;
+    /** Minimum visible duration for `isRefetching` after any query completes. On localhost a delta
+     *  poll can resolve in tens of ms — too brief for the spinner's 1s rotation to register visually,
+     *  and quick enough that React may batch the start/finish transitions. Pulsing for this duration
+     *  on completion (~144° of rotation at 400ms) makes each poll perceptible as a heartbeat.
+     *  Default 400ms. */
+    minRefetchSpinMs?: number;
+    /** Window during which a delta-arrived row's key stays in `recentlyAddedKeys` so the list view
+     *  can apply its `animate-row-highlight` class. Should match the CSS animation duration
+     *  (currently 1_000ms — see `index.css`). Default 1_000ms. */
+    deltaHighlightMs?: number;
+}
+/** Returns true when the cursor should be considered stale and re-seeded.
+ *  Exported for testing — pure function of timestamps. */
+export declare function shouldResetAfterIdle(lastSuccessAt: number, now: number, thresholdMs: number): boolean;
+/** 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. */
+export declare function shouldPinLightList(status: number | undefined, firstServerErrorAt: number | undefined, now: number): boolean;
+type FetchTracesFnArgs = TracesFilters & {
+    client: ReturnType<typeof useMastraClient>;
+} & ({
+    mode: 'delta';
+    after?: string;
+    limit?: number;
+} | {
+    mode?: 'page';
+    page: number;
+    perPage: number;
+});
+declare const fetchTracesFn: (args: FetchTracesFnArgs) => Promise<{
+    pagination?: {
+        total: number;
+        page: number;
+        perPage: number | false;
+        hasMore: boolean;
+    } | undefined;
+    delta?: {
+        limit: number;
+        hasMore: boolean;
+    } | undefined;
+    deltaCursor?: string | undefined;
+    spans: {
+        traceId: string;
+        spanId: string;
+        name: string;
+        spanType: "agent_run" | "agent_signal" | "classifier_evaluation" | "client_tool_call" | "generic" | "graph_action" | "mapping" | "mcp_server_request" | "mcp_tool_call" | "memory_operation" | "model_chunk" | "model_generation" | "model_inference" | "model_step" | "processor_run" | "provider_tool_call" | "rag_action" | "rag_embedding" | "rag_ingestion" | "rag_vector_operation" | "scorer_run" | "scorer_step" | "skill_action" | "skill_resolution" | "tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_loop" | "workflow_parallel" | "workflow_run" | "workflow_sleep" | "workflow_step" | "workflow_wait_event" | "workspace_action";
+        isEvent: boolean;
+        startedAt: string;
+        parentSpanId?: (string | null) | undefined;
+        endedAt?: string | null | undefined;
+        error?: (unknown | null) | undefined;
+        status?: (('success' | 'error' | 'running') | null) | undefined;
+        entityType?: (("agent" | "classifier" | "input_processor" | "input_step_processor" | "mcp_server" | "memory" | "output_processor" | "output_step_processor" | "rag_ingestion" | "scorer" | "tool" | "tool_result_processor" | "trajectory" | "workflow_run" | "workflow_step") | null) | undefined;
+        entityId?: (string | null) | undefined;
+        entityName?: (string | null) | undefined;
+        threadId?: ((string | null) | undefined) | null;
+        resourceId?: ((string | null) | undefined) | null;
+        metadata?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        inputPreview?: (string | null) | undefined;
+        outputPreview?: (string | null) | undefined;
+        errorPreview?: (string | null) | undefined;
+        createdAt: string;
+        updatedAt: string | null;
+    }[];
+} | {
+    pagination?: {
+        total: number;
+        page: number;
+        perPage: number | false;
+        hasMore: boolean;
+    } | undefined;
+    delta?: {
+        limit: number;
+        hasMore: boolean;
+    } | undefined;
+    deltaCursor?: string | undefined;
+    branches: {
+        traceId: string;
+        spanId: string;
+        name: string;
+        spanType: "agent_run" | "agent_signal" | "classifier_evaluation" | "client_tool_call" | "generic" | "graph_action" | "mapping" | "mcp_server_request" | "mcp_tool_call" | "memory_operation" | "model_chunk" | "model_generation" | "model_inference" | "model_step" | "processor_run" | "provider_tool_call" | "rag_action" | "rag_embedding" | "rag_ingestion" | "rag_vector_operation" | "scorer_run" | "scorer_step" | "skill_action" | "skill_resolution" | "tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_loop" | "workflow_parallel" | "workflow_run" | "workflow_sleep" | "workflow_step" | "workflow_wait_event" | "workspace_action";
+        isEvent: boolean;
+        startedAt: string;
+        parentSpanId?: (string | null) | undefined;
+        entityType?: (("agent" | "classifier" | "input_processor" | "input_step_processor" | "mcp_server" | "memory" | "output_processor" | "output_step_processor" | "rag_ingestion" | "scorer" | "tool" | "tool_result_processor" | "trajectory" | "workflow_run" | "workflow_step") | null) | undefined;
+        entityId?: (string | null) | undefined;
+        entityName?: (string | null) | undefined;
+        parentEntityType?: (("agent" | "classifier" | "input_processor" | "input_step_processor" | "mcp_server" | "memory" | "output_processor" | "output_step_processor" | "rag_ingestion" | "scorer" | "tool" | "tool_result_processor" | "trajectory" | "workflow_run" | "workflow_step") | null) | undefined;
+        parentEntityId?: (string | null) | undefined;
+        parentEntityName?: (string | null) | undefined;
+        rootEntityType?: (("agent" | "classifier" | "input_processor" | "input_step_processor" | "mcp_server" | "memory" | "output_processor" | "output_step_processor" | "rag_ingestion" | "scorer" | "tool" | "tool_result_processor" | "trajectory" | "workflow_run" | "workflow_step") | null) | undefined;
+        rootEntityId?: (string | null) | undefined;
+        rootEntityName?: (string | null) | undefined;
+        userId?: (string | null) | undefined;
+        organizationId?: (string | null) | undefined;
+        resourceId?: (string | null) | undefined;
+        runId?: (string | null) | undefined;
+        sessionId?: (string | null) | undefined;
+        threadId?: (string | null) | undefined;
+        requestId?: (string | null) | undefined;
+        environment?: (string | null) | undefined;
+        serviceName?: (string | null) | undefined;
+        scope?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        entityVersionId?: (string | null) | undefined;
+        parentEntityVersionId?: (string | null) | undefined;
+        rootEntityVersionId?: (string | null) | undefined;
+        experimentId?: (string | null) | undefined;
+        source?: (string | null) | undefined;
+        metadata?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        tags?: (string[] | null) | undefined;
+        attributes?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        links?: (unknown[] | null) | undefined;
+        input?: (unknown | null) | undefined;
+        output?: (unknown | null) | undefined;
+        error?: (unknown | null) | undefined;
+        endedAt?: string | null | undefined;
+        requestContext?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        inputPreview?: (string | null) | undefined;
+        outputPreview?: (string | null) | undefined;
+        errorPreview?: (string | null) | undefined;
+        timeToFirstChunkMs?: (number | null) | undefined;
+        externalParentSpanId?: (string | null) | undefined;
+        resumedFromSpanId?: (string | null) | undefined;
+        model?: (string | null) | undefined;
+        provider?: (string | null) | undefined;
+        outcome?: (string | null) | undefined;
+        stopReason?: (string | null) | undefined;
+        stopReasonContext?: ({
+            [key: string]: unknown;
+        } | null) | undefined;
+        timeToFirstTokenMs?: (number | null) | undefined;
+        errorCount?: (number | null) | undefined;
+        createdAt: string;
+        updatedAt: string | null;
+        status: 'success' | 'error' | 'running';
+    }[];
+}>;
+export declare const TRACES_PER_PAGE = 25;
+export interface TracesFilters {
+    filters?: ListTracesArgs['filters'] | ListBranchesArgs['filters'];
+    listMode?: TraceListMode;
+}
+/** Returns the next page number if the server indicates more pages are available. */
+export declare function getTracesNextPageParam(lastPage: ListTracesLightResponse | ListBranchesResponse | undefined, _allPages: unknown, lastPageParam: number): number | undefined;
+type TracesPageResponse = ListTracesLightResponse | ListBranchesResponse;
+/** 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. */
+export declare function selectUniqueTraces(data: {
+    pages: TracesPageResponse[];
+}): {
+    spans: LightSpanRecord[];
+    deltaCursor: string | undefined;
+};
+/** 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. */
+export declare function refreshPage0Rows(old: InfiniteData<TracesPageResponse> | undefined, refreshed: ListTracesLightResponse | ListBranchesResponse, listMode: TraceListMode): InfiniteData<TracesPageResponse> | undefined;
+/** 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. */
+export declare function mergeDeltaIntoPage0(old: InfiniteData<TracesPageResponse> | undefined, delta: ListTracesLightResponse | ListBranchesResponse, listMode: TraceListMode): InfiniteData<TracesPageResponse> | undefined;
+export interface UseTracesArgs extends TracesFilters {
+    enabled?: boolean;
+    /** Optional overrides for the live-tail polling tunables. Any omitted fields fall back to the
+     *  built-in defaults; pass only what you want to change. */
+    polling?: TracesPollingConfig;
+    /** TanStack overrides for each underlying query, spread last. The hook consumes each query's data internally, so `select` must keep the default shape. */
+    queryOptions?: {
+        traces?: MastraInfiniteQueryOptions<TracesPageResponse, ReturnType<typeof selectUniqueTraces>, readonly ['traces', TraceListMode, TracesFilters['filters']], number>;
+        delta?: MastraQueryOptions<Awaited<ReturnType<typeof fetchTracesFn>> | null>;
+        statusRefresh?: MastraQueryOptions<Awaited<ReturnType<typeof fetchTracesFn>>>;
+    };
+}
+interface UseTracesReturn {
+    data: {
+        spans: LightSpanRecord[];
+        deltaCursor: string | undefined;
+    } | undefined;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: () => void;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    setEndOfListElement: (node: HTMLDivElement | null) => void;
+    isRefetching: boolean;
+    autoRefetch: boolean;
+    setAutoRefetch: (v: boolean) => void;
+    recentlyAddedKeys: Set<string>;
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    isFetching: boolean;
+    isSuccess: boolean;
+    fetchStatus: 'idle' | 'fetching' | 'paused';
+    refetch: () => void;
+}
+export declare const useTraces: (args: UseTracesArgs) => UseTracesReturn;
+export {};
+//# sourceMappingURL=use-traces.d.ts.map