@mastra/playground-ui 55.0.0 → 56.0.0-alpha.10

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

@@ -1,6 +1,5 @@
 import { MastraClient } from '@mastra/client-js';
 import { UseQueryResult } from '@tanstack/react-query';
-import { SearchableSpan } from '../types';
 /**
  * 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
@@ -9,141 +8,168 @@ import { SearchableSpan } from '../types';
 export declare const traceSpansQueryOptions: (client: MastraClient, traceId: string | null | undefined) => import('@tanstack/react-query').OmitKeyof<import('@tanstack/react-query').UseQueryOptions<{
     traceId: string;
     spans: {
-        createdAt: Date;
-        updatedAt: Date | null;
         traceId: string;
         spanId: string;
         name: string;
-        spanType: import('@mastra/core/observability').SpanType;
+        spanType: "workflow_run" | "rag_ingestion" | "workflow_step" | "agent_run" | "scorer_run" | "scorer_step" | "generic" | "model_generation" | "model_step" | "model_inference" | "model_chunk" | "mcp_tool_call" | "processor_run" | "tool_call" | "client_tool_call" | "provider_tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_parallel" | "workflow_loop" | "workflow_sleep" | "workflow_wait_event" | "memory_operation" | "workspace_action" | "rag_embedding" | "rag_vector_operation" | "rag_action" | "graph_action" | "mapping" | "skill_resolution" | "skill_action" | "agent_signal";
         isEvent: boolean;
-        startedAt: Date;
-        entityType?: import('@mastra/core/observability').EntityType | null | undefined;
-        entityId?: string | null | undefined;
-        entityName?: string | null | undefined;
-        parentEntityType?: import('@mastra/core/observability').EntityType | null | undefined;
-        parentEntityId?: string | null | undefined;
-        parentEntityName?: string | null | undefined;
-        rootEntityType?: import('@mastra/core/observability').EntityType | 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?: Record<string, unknown> | null | undefined;
-        entityVersionId?: string | null | undefined;
-        parentEntityVersionId?: string | null | undefined;
-        rootEntityVersionId?: string | null | undefined;
-        source?: string | null | undefined;
-        metadata?: Record<string, unknown> | null | undefined;
+        startedAt: string;
+        parentSpanId?: (string | null) | undefined | undefined;
+        entityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        entityId?: (string | null) | undefined | undefined;
+        entityName?: (string | null) | undefined | undefined;
+        parentEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        parentEntityId?: (string | null) | undefined | undefined;
+        parentEntityName?: (string | null) | undefined | undefined;
+        rootEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        rootEntityId?: (string | null) | undefined | undefined;
+        rootEntityName?: (string | null) | undefined | undefined;
+        userId?: (string | null) | undefined | undefined;
+        organizationId?: (string | null) | undefined | undefined;
+        resourceId?: (string | null) | undefined | undefined;
+        runId?: (string | null) | undefined | undefined;
+        sessionId?: (string | null) | undefined | undefined;
+        threadId?: (string | null) | undefined | undefined;
+        requestId?: (string | null) | undefined | undefined;
+        environment?: (string | null) | undefined | undefined;
+        serviceName?: (string | null) | undefined | undefined;
+        scope?: {
+            [x: string]: unknown;
+        } | null | undefined;
+        entityVersionId?: (string | null) | undefined | undefined;
+        parentEntityVersionId?: (string | null) | undefined | undefined;
+        rootEntityVersionId?: (string | null) | undefined | undefined;
+        experimentId?: (string | null) | undefined | undefined;
+        source?: (string | null) | undefined | undefined;
+        metadata?: {
+            [x: string]: unknown;
+        } | null | undefined;
         tags?: string[] | null | undefined;
-        parentSpanId?: string | null | undefined;
-        experimentId?: string | null | undefined;
-        attributes?: Record<string, unknown> | null | undefined;
+        attributes?: {
+            [x: string]: unknown;
+        } | null | undefined;
         links?: unknown[] | null | undefined;
-        input?: unknown;
-        output?: unknown;
-        error?: unknown;
-        endedAt?: Date | null | undefined;
-        requestContext?: Record<string, unknown> | null | undefined;
+        input?: (unknown | null) | undefined;
+        output?: (unknown | null) | undefined;
+        error?: (unknown | null) | undefined;
+        endedAt?: string | null | undefined;
+        requestContext?: {
+            [x: string]: unknown;
+        } | null | undefined;
+        createdAt: string;
+        updatedAt: string | null;
+        status: "success" | "error" | "running";
     }[];
 }, Error, {
     traceId: string;
     spans: {
-        createdAt: Date;
-        updatedAt: Date | null;
         traceId: string;
         spanId: string;
         name: string;
-        spanType: import('@mastra/core/observability').SpanType;
+        spanType: "workflow_run" | "rag_ingestion" | "workflow_step" | "agent_run" | "scorer_run" | "scorer_step" | "generic" | "model_generation" | "model_step" | "model_inference" | "model_chunk" | "mcp_tool_call" | "processor_run" | "tool_call" | "client_tool_call" | "provider_tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_parallel" | "workflow_loop" | "workflow_sleep" | "workflow_wait_event" | "memory_operation" | "workspace_action" | "rag_embedding" | "rag_vector_operation" | "rag_action" | "graph_action" | "mapping" | "skill_resolution" | "skill_action" | "agent_signal";
         isEvent: boolean;
-        startedAt: Date;
-        entityType?: import('@mastra/core/observability').EntityType | null | undefined;
-        entityId?: string | null | undefined;
-        entityName?: string | null | undefined;
-        parentEntityType?: import('@mastra/core/observability').EntityType | null | undefined;
-        parentEntityId?: string | null | undefined;
-        parentEntityName?: string | null | undefined;
-        rootEntityType?: import('@mastra/core/observability').EntityType | 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?: Record<string, unknown> | null | undefined;
-        entityVersionId?: string | null | undefined;
-        parentEntityVersionId?: string | null | undefined;
-        rootEntityVersionId?: string | null | undefined;
-        source?: string | null | undefined;
-        metadata?: Record<string, unknown> | null | undefined;
+        startedAt: string;
+        parentSpanId?: (string | null) | undefined | undefined;
+        entityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        entityId?: (string | null) | undefined | undefined;
+        entityName?: (string | null) | undefined | undefined;
+        parentEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        parentEntityId?: (string | null) | undefined | undefined;
+        parentEntityName?: (string | null) | undefined | undefined;
+        rootEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+        rootEntityId?: (string | null) | undefined | undefined;
+        rootEntityName?: (string | null) | undefined | undefined;
+        userId?: (string | null) | undefined | undefined;
+        organizationId?: (string | null) | undefined | undefined;
+        resourceId?: (string | null) | undefined | undefined;
+        runId?: (string | null) | undefined | undefined;
+        sessionId?: (string | null) | undefined | undefined;
+        threadId?: (string | null) | undefined | undefined;
+        requestId?: (string | null) | undefined | undefined;
+        environment?: (string | null) | undefined | undefined;
+        serviceName?: (string | null) | undefined | undefined;
+        scope?: {
+            [x: string]: unknown;
+        } | null | undefined;
+        entityVersionId?: (string | null) | undefined | undefined;
+        parentEntityVersionId?: (string | null) | undefined | undefined;
+        rootEntityVersionId?: (string | null) | undefined | undefined;
+        experimentId?: (string | null) | undefined | undefined;
+        source?: (string | null) | undefined | undefined;
+        metadata?: {
+            [x: string]: unknown;
+        } | null | undefined;
         tags?: string[] | null | undefined;
-        parentSpanId?: string | null | undefined;
-        experimentId?: string | null | undefined;
-        attributes?: Record<string, unknown> | null | undefined;
+        attributes?: {
+            [x: string]: unknown;
+        } | null | undefined;
         links?: unknown[] | null | undefined;
-        input?: unknown;
-        output?: unknown;
-        error?: unknown;
-        endedAt?: Date | null | undefined;
-        requestContext?: Record<string, unknown> | null | undefined;
+        input?: (unknown | null) | undefined;
+        output?: (unknown | null) | undefined;
+        error?: (unknown | null) | undefined;
+        endedAt?: string | null | undefined;
+        requestContext?: {
+            [x: string]: unknown;
+        } | null | undefined;
+        createdAt: string;
+        updatedAt: string | null;
+        status: "success" | "error" | "running";
     }[];
 }, (string | null | undefined)[]>, "queryFn"> & {
     queryFn?: import('@tanstack/react-query').QueryFunction<{
         traceId: string;
         spans: {
-            createdAt: Date;
-            updatedAt: Date | null;
             traceId: string;
             spanId: string;
             name: string;
-            spanType: import('@mastra/core/observability').SpanType;
+            spanType: "workflow_run" | "rag_ingestion" | "workflow_step" | "agent_run" | "scorer_run" | "scorer_step" | "generic" | "model_generation" | "model_step" | "model_inference" | "model_chunk" | "mcp_tool_call" | "processor_run" | "tool_call" | "client_tool_call" | "provider_tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_parallel" | "workflow_loop" | "workflow_sleep" | "workflow_wait_event" | "memory_operation" | "workspace_action" | "rag_embedding" | "rag_vector_operation" | "rag_action" | "graph_action" | "mapping" | "skill_resolution" | "skill_action" | "agent_signal";
             isEvent: boolean;
-            startedAt: Date;
-            entityType?: import('@mastra/core/observability').EntityType | null | undefined;
-            entityId?: string | null | undefined;
-            entityName?: string | null | undefined;
-            parentEntityType?: import('@mastra/core/observability').EntityType | null | undefined;
-            parentEntityId?: string | null | undefined;
-            parentEntityName?: string | null | undefined;
-            rootEntityType?: import('@mastra/core/observability').EntityType | 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?: Record<string, unknown> | null | undefined;
-            entityVersionId?: string | null | undefined;
-            parentEntityVersionId?: string | null | undefined;
-            rootEntityVersionId?: string | null | undefined;
-            source?: string | null | undefined;
-            metadata?: Record<string, unknown> | null | undefined;
+            startedAt: string;
+            parentSpanId?: (string | null) | undefined | undefined;
+            entityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+            entityId?: (string | null) | undefined | undefined;
+            entityName?: (string | null) | undefined | undefined;
+            parentEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+            parentEntityId?: (string | null) | undefined | undefined;
+            parentEntityName?: (string | null) | undefined | undefined;
+            rootEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+            rootEntityId?: (string | null) | undefined | undefined;
+            rootEntityName?: (string | null) | undefined | undefined;
+            userId?: (string | null) | undefined | undefined;
+            organizationId?: (string | null) | undefined | undefined;
+            resourceId?: (string | null) | undefined | undefined;
+            runId?: (string | null) | undefined | undefined;
+            sessionId?: (string | null) | undefined | undefined;
+            threadId?: (string | null) | undefined | undefined;
+            requestId?: (string | null) | undefined | undefined;
+            environment?: (string | null) | undefined | undefined;
+            serviceName?: (string | null) | undefined | undefined;
+            scope?: {
+                [x: string]: unknown;
+            } | null | undefined;
+            entityVersionId?: (string | null) | undefined | undefined;
+            parentEntityVersionId?: (string | null) | undefined | undefined;
+            rootEntityVersionId?: (string | null) | undefined | undefined;
+            experimentId?: (string | null) | undefined | undefined;
+            source?: (string | null) | undefined | undefined;
+            metadata?: {
+                [x: string]: unknown;
+            } | null | undefined;
             tags?: string[] | null | undefined;
-            parentSpanId?: string | null | undefined;
-            experimentId?: string | null | undefined;
-            attributes?: Record<string, unknown> | null | undefined;
+            attributes?: {
+                [x: string]: unknown;
+            } | null | undefined;
             links?: unknown[] | null | undefined;
-            input?: unknown;
-            output?: unknown;
-            error?: unknown;
-            endedAt?: Date | null | undefined;
-            requestContext?: Record<string, unknown> | null | undefined;
+            input?: (unknown | null) | undefined;
+            output?: (unknown | null) | undefined;
+            error?: (unknown | null) | undefined;
+            endedAt?: string | null | undefined;
+            requestContext?: {
+                [x: string]: unknown;
+            } | null | undefined;
+            createdAt: string;
+            updatedAt: string | null;
+            status: "success" | "error" | "running";
         }[];
     }, (string | null | undefined)[], never> | undefined;
 } & {
@@ -151,48 +177,57 @@ export declare const traceSpansQueryOptions: (client: MastraClient, traceId: str
         [dataTagSymbol]: {
             traceId: string;
             spans: {
-                createdAt: Date;
-                updatedAt: Date | null;
                 traceId: string;
                 spanId: string;
                 name: string;
-                spanType: import('@mastra/core/observability').SpanType;
+                spanType: "workflow_run" | "rag_ingestion" | "workflow_step" | "agent_run" | "scorer_run" | "scorer_step" | "generic" | "model_generation" | "model_step" | "model_inference" | "model_chunk" | "mcp_tool_call" | "processor_run" | "tool_call" | "client_tool_call" | "provider_tool_call" | "workflow_conditional" | "workflow_conditional_eval" | "workflow_parallel" | "workflow_loop" | "workflow_sleep" | "workflow_wait_event" | "memory_operation" | "workspace_action" | "rag_embedding" | "rag_vector_operation" | "rag_action" | "graph_action" | "mapping" | "skill_resolution" | "skill_action" | "agent_signal";
                 isEvent: boolean;
-                startedAt: Date;
-                entityType?: import('@mastra/core/observability').EntityType | null | undefined;
-                entityId?: string | null | undefined;
-                entityName?: string | null | undefined;
-                parentEntityType?: import('@mastra/core/observability').EntityType | null | undefined;
-                parentEntityId?: string | null | undefined;
-                parentEntityName?: string | null | undefined;
-                rootEntityType?: import('@mastra/core/observability').EntityType | 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?: Record<string, unknown> | null | undefined;
-                entityVersionId?: string | null | undefined;
-                parentEntityVersionId?: string | null | undefined;
-                rootEntityVersionId?: string | null | undefined;
-                source?: string | null | undefined;
-                metadata?: Record<string, unknown> | null | undefined;
+                startedAt: string;
+                parentSpanId?: (string | null) | undefined | undefined;
+                entityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+                entityId?: (string | null) | undefined | undefined;
+                entityName?: (string | null) | undefined | undefined;
+                parentEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+                parentEntityId?: (string | null) | undefined | undefined;
+                parentEntityName?: (string | null) | undefined | undefined;
+                rootEntityType?: ("agent" | "workflow_run" | "tool" | "scorer" | "rag_ingestion" | "trajectory" | "input_processor" | "input_step_processor" | "output_processor" | "output_step_processor" | "tool_result_processor" | "workflow_step" | "memory") | null | undefined;
+                rootEntityId?: (string | null) | undefined | undefined;
+                rootEntityName?: (string | null) | undefined | undefined;
+                userId?: (string | null) | undefined | undefined;
+                organizationId?: (string | null) | undefined | undefined;
+                resourceId?: (string | null) | undefined | undefined;
+                runId?: (string | null) | undefined | undefined;
+                sessionId?: (string | null) | undefined | undefined;
+                threadId?: (string | null) | undefined | undefined;
+                requestId?: (string | null) | undefined | undefined;
+                environment?: (string | null) | undefined | undefined;
+                serviceName?: (string | null) | undefined | undefined;
+                scope?: {
+                    [x: string]: unknown;
+                } | null | undefined;
+                entityVersionId?: (string | null) | undefined | undefined;
+                parentEntityVersionId?: (string | null) | undefined | undefined;
+                rootEntityVersionId?: (string | null) | undefined | undefined;
+                experimentId?: (string | null) | undefined | undefined;
+                source?: (string | null) | undefined | undefined;
+                metadata?: {
+                    [x: string]: unknown;
+                } | null | undefined;
                 tags?: string[] | null | undefined;
-                parentSpanId?: string | null | undefined;
-                experimentId?: string | null | undefined;
-                attributes?: Record<string, unknown> | null | undefined;
+                attributes?: {
+                    [x: string]: unknown;
+                } | null | undefined;
                 links?: unknown[] | null | undefined;
-                input?: unknown;
-                output?: unknown;
-                error?: unknown;
-                endedAt?: Date | null | undefined;
-                requestContext?: Record<string, unknown> | null | undefined;
+                input?: (unknown | null) | undefined;
+                output?: (unknown | null) | undefined;
+                error?: (unknown | null) | undefined;
+                endedAt?: string | null | undefined;
+                requestContext?: {
+                    [x: string]: unknown;
+                } | null | undefined;
+                createdAt: string;
+                updatedAt: string | null;
+                status: "success" | "error" | "running";
             }[];
         };
         [dataTagErrorSymbol]: Error;
@@ -207,15 +242,18 @@ export declare const traceSpansQueryOptions: (client: MastraClient, traceId: str
  * 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']>>;
+type SearchableTraceSpansData = Omit<NonNullable<TraceSpansData>, 'spans'> & {
+    spans: Array<NonNullable<TraceSpansData>['spans'][number] & {
+        searchText: string;
+    }>;
+};
 export declare function useTraceSpans(traceId: string | null | undefined, { passive }?: {
     passive?: boolean;
-}): UseQueryResult<{
-    traceId: string;
-    spans: SearchableSpan[];
-} | null>;
-export type TraceSpansData = Awaited<ReturnType<MastraClient['getTrace']>>;
+}): UseQueryResult<SearchableTraceSpansData | null>;
 /**
  * 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: string[], select: (traceId: string, data: TraceSpansData) => T, fallback: (traceId: string) => T): T[];
+export {};

package/dist/src/domains/traces/hooks/use-trace-url-state.d.ts

@@ -1,3 +1,4 @@
+import { TraceSpanView } from '../components/trace-data-panel-view';
 import { SpanTab, TraceDatePreset } from '../index';
 import { EntityOptions, TraceListMode, TraceStatusFilter } from '../trace-filters';
 import { PropertyFilterToken } from '../../../ds/components/PropertyFilter/types';
@@ -27,6 +28,8 @@ export interface UseTraceUrlStateResult {
      *  user navigates between spans inside the panel (which only changes `spanIdParam`). */
     anchorSpanIdParam: string | undefined;
     spanTabParam: SpanTab | undefined;
+    /** Which view the trace column shows; `tree` is the default and is not written to the URL. */
+    spanViewParam: TraceSpanView;
     scoreIdParam: string | undefined;
     /** Span ids featured in the timeline (e.g. the spans behind a reconstructed message). Empty when unset. */
     highlightSpanIdsParam: string[];
@@ -47,6 +50,7 @@ export interface UseTraceUrlStateResult {
     /** Convenience: clears the featured span selection. Equivalent to `handleSpanChange(null)`. */
     handleSpanClose: () => void;
     handleSpanTabChange: (tab: SpanTab) => void;
+    handleSpanViewChange: (view: TraceSpanView) => void;
     /** Selects a span AND switches its panel tab in a single URL update. Use when both must change
      *  from one interaction (e.g. "Evaluate Trace"). Calling `handleSpanChange` + `handleSpanTabChange`
      *  separately races: each functional `setSearchParams` updater reads the same pre-update
@@ -60,6 +64,9 @@ export interface UseTraceUrlStateResult {
     handleListModeChange: (mode: TraceListMode) => void;
     handleFilterTokensChange: (nextTokens: PropertyFilterToken[]) => void;
     handleDateChange: (value: Date | undefined, type: 'from' | 'to') => void;
+    /** Writes both ends of a custom range in one URL update (two `handleDateChange` calls in the
+     *  same tick would clobber each other through react-router's closure-bound setter). */
+    handleDateRangeChange: (from: Date | undefined, to: Date | undefined) => void;
     handleDatePresetChange: (preset: TraceDatePreset) => void;
     handleRemoveAll: () => void;
     /** Lower-level helper used by `handleClear`: writes a token set and clears the trace/span selection. */

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

@@ -1,6 +1,11 @@
-import { LightSpanRecord, ListBranchesArgs, ListBranchesResponse, ListTracesArgs, ListTracesLightResponse } from '@mastra/core/storage';
+import { MastraClient } from '@mastra/client-js';
 import { InfiniteData } from '@tanstack/react-query';
 import { TraceListMode } from '../trace-filters';
+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. */
@@ -69,6 +74,7 @@ export declare function refreshPage0Rows(old: InfiniteData<TracesPageResponse> |
  *  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;

package/dist/src/domains/traces/index.d.ts

@@ -2,5 +2,6 @@ export * from './components';
 export * from './hooks';
 export * from './utils';
 export * from './trace-filters';
+export * from './trace-query-filters';
 export type { UISpan, UISpanStyle, TraceDatePreset, EntityOptions, SpanTab } from './types';
 export { CONTEXT_FIELD_IDS } from './types';

package/dist/src/domains/traces/trace-filters.d.ts

@@ -1,7 +1,9 @@
 import { EntityType } from '@mastra/core/observability';
 import { ListTracesArgs } from '@mastra/core/storage';
+import { TraceMetadataFilterField } from './hooks/use-trace-metadata-filter-fields';
 import { TraceDatePreset } from './types';
-import { PropertyFilterField, PropertyFilterToken } from '../../ds/components/PropertyFilter/types';
+import { FilterBarField, FilterBarItem, FilterBarOperator } from '../../ds/components/FilterBar/types';
+import { PropertyFilterToken } from '../../ds/components/PropertyFilter/types';
 type EntityTypeValue = `${EntityType}`;
 export type EntityOptions = {
     label: string;
@@ -41,6 +43,13 @@ export declare const TRACE_STATUS_OPTIONS: readonly [{
  *  rather than the generic `filter*` set, but appear as rows in the Filter
  *  popover so users can manage all filters from one place. */
 export declare const TRACE_SYNTHETIC_FILTER_FIELD_IDS: readonly ["rootEntityType", "status"];
+/** Discovered `metadata.<key>` fields are dynamic, so they use a prefix-based URL
+ *  scheme (`filterMetadata.<key>`) instead of the fixed `filter*` param map. */
+export declare const TRACE_METADATA_FILTER_FIELD_PREFIX = "metadata.";
+export declare const TRACE_METADATA_FILTER_PARAM_PREFIX = "filterMetadata.";
+export declare const isTraceMetadataFieldId: (fieldId: string) => boolean;
+export declare const metadataFieldIdToParam: (fieldId: string) => string;
+export declare const metadataParamToFieldId: (param: string) => string;
 export declare const TRACE_ROOT_ENTITY_TYPE_PARAM = "rootEntityType";
 export declare const TRACE_STATUS_PARAM = "status";
 export declare const TRACE_LIST_MODE_PARAM = "listMode";
@@ -94,18 +103,30 @@ export declare function loadTraceFiltersFromStorage(storageKey?: string): URLSea
  *  to hydrate from localStorage on page mount (we only hydrate when the URL is
  *  filter-clean, i.e. the user landed here via a plain sidebar nav). */
 export declare function hasAnyTraceFilterParams(params: URLSearchParams): boolean;
-export declare function createTracePropertyFilterFields({ availableTags, availableRootEntityNames, availableServiceNames, availableEnvironments, loading, }: {
-    availableTags: string[];
+/** The trace query API only runs equality (`eq`) and set membership (`in`)
+ *  predicates, so the FilterBar offers exactly those two operators. */
+export declare const TRACE_FILTER_BAR_OPERATORS: FilterBarOperator[];
+export declare const traceFilterFieldIcon: (fieldId: string) => any;
+/** Stable per-field accent; known keys use a curated hue, others fall back to a hashed one. */
+export declare const traceFilterFieldColor: (fieldId: string) => string;
+/** FilterBar field definitions for the trace pages. Fields the query API cannot
+ *  filter on (see `TRACE_QUERY_UNSUPPORTED_FILTER_FIELDS`) are omitted, as is the
+ *  `running` status, so no chip advertises a filter that has no effect. Hidden
+ *  fields are never offered in the input's field step but still label existing
+ *  (e.g. scoped, read-only) chips. */
+export declare function createTraceFilterBarFields({ availableRootEntityNames, availableEnvironments, hiddenFieldIds, metadataFields, }: {
     availableRootEntityNames: string[];
-    availableServiceNames: string[];
     availableEnvironments: string[];
-    loading?: {
-        tags?: boolean;
-        entityNames?: boolean;
-        serviceNames?: boolean;
-        environments?: boolean;
-    };
-}): PropertyFilterField[];
+    hiddenFieldIds?: readonly string[];
+    /** Discovered `metadata.<key>` paths with a lazy value-suggestions resolver each. */
+    metadataFields?: readonly TraceMetadataFilterField[];
+}): FilterBarField[];
+/** One FilterBar item per token, keyed by field id so chip order == URL order.
+ *  Empty values ('' / []) are kept: that's a pending chip whose field was just
+ *  changed and whose value hasn't been picked yet (the query builder skips it).
+ *  Only the legacy 'Any' sentinel is mapped back to an empty value. */
+export declare function traceTokensToFilterBarItems(tokens: PropertyFilterToken[]): FilterBarItem[];
+export declare function filterBarItemsToTraceTokens(items: FilterBarItem[]): PropertyFilterToken[];
 /**
  * Read filter tokens from URL search params preserving the order in which each
  * filter was first added (URLSearchParams iterates in insertion order). This
@@ -128,10 +149,4 @@ export declare function buildTraceListFilters({ rootEntityType, status, dateFrom
     dateTo?: Date;
     tokens: PropertyFilterToken[];
 }): ListTracesArgs['filters'];
-/**
- * "Clear" semantics: keep all filter pills but neutralize each value.
- * '' for text fields, 'Any' for single-select pick-multi, [] for multi-select pick-multi.
- * Date range is intentionally NOT touched here — that's a separate concern.
- */
-export declare function neutralizeFilterTokens(filterFields: PropertyFilterField[], filterTokens: PropertyFilterToken[]): PropertyFilterToken[];
 export {};

package/dist/src/domains/traces/trace-query-filters.d.ts

@@ -0,0 +1,17 @@
+import { QueryTracesInput } from '@mastra/client-js';
+import { buildTraceListFilters } from './trace-filters';
+export declare const TRACE_QUERY_UNSUPPORTED_FILTER_FIELDS: Set<string>;
+export declare function buildTraceQueryRequest({ rootEntityType, status, dateFrom, dateTo, tokens, now, }: Parameters<typeof buildTraceListFilters>[0] & {
+    now: Date;
+}): Pick<QueryTracesInput, 'timeRange' | 'where'>;
+export declare const TRACE_QUERY_DISCOVERY_MAX_RANGE_MS: number;
+/** Discovery endpoints reject ranges wider than 31 days (and `from >= to`); clamp
+ *  the page's selected range so wide custom ranges still get field suggestions
+ *  for the most recent window. */
+export declare function clampTraceDiscoveryTimeRange(timeRange: {
+    from: string;
+    to: string;
+}): {
+    from: string;
+    to: string;
+};

package/dist/src/domains/traces/types.d.ts

@@ -1,6 +1,10 @@
+import { MastraClient } from '@mastra/client-js';
 import { EntityType } from '@mastra/core/observability';
-import { LightSpanRecord } from '@mastra/core/storage';
 import { ReactNode } from 'react';
+type GetTraceLightResponse = Awaited<ReturnType<MastraClient['getTraceLight']>>;
+type GetSpanResponse = Awaited<ReturnType<MastraClient['getSpan']>>;
+export type LightSpanRecord = GetTraceLightResponse['spans'][number];
+export type SpanRecord = GetSpanResponse['span'];
 /**
  * A light span carrying a precomputed haystack of everything it holds.
  *
@@ -55,3 +59,4 @@ export type TraceDatePreset = 'all' | 'last-24h' | 'last-3d' | 'last-7d' | 'last
 export type SpanTab = 'details' | 'feedback';
 /** Canonical list of context field IDs used for trace filtering and value extraction */
 export declare const CONTEXT_FIELD_IDS: readonly ["environment", "serviceName", "source", "scope", "userId", "organizationId", "resourceId", "runId", "sessionId", "threadId", "requestId", "experimentId", "spanType", "entityName", "parentEntityType", "parentEntityId", "parentEntityName", "rootEntityType", "rootEntityId", "rootEntityName"];
+export {};

package/dist/src/domains/traces/utils/filter-spans-keeping-ancestors.d.ts

@@ -1,4 +1,4 @@
-import { LightSpanRecord } from '@mastra/core/storage';
+import { LightSpanRecord } from '../types';
 /**
  * Filter a flat span list down to the spans matching `predicate`, plus every
  * ancestor needed to keep those spans connected to their root, plus the whole

package/dist/src/domains/traces/utils/span-utils.d.ts

@@ -1,4 +1,4 @@
-import { SpanRecord } from '@mastra/core/storage';
+import { SpanRecord } from '../types';
 export declare function formatSpanDuration(startedAt: Date | string | null | undefined, endedAt: Date | string | null | undefined): string | undefined;
 export declare function formatSpanDurationExact(startedAt: Date | string | null | undefined, endedAt: Date | string | null | undefined): string | undefined;
 /** `X.XXX s`, matching the timeline timing column. */

package/dist/src/domains/traces/utils/to-searchable-spans.d.ts

@@ -1,5 +1,4 @@
-import { LightSpanRecord } from '@mastra/core/storage';
-import { SearchableSpan } from '../types';
+import { LightSpanRecord, SearchableSpan } from '../types';
 /**
  * Attach a precomputed search haystack to each span.
  *
@@ -14,7 +13,9 @@ import { SearchableSpan } from '../types';
  *
  * Inputs are left untouched; each result is a new object.
  */
-export declare function toSearchableSpans(spans: LightSpanRecord[]): SearchableSpan[];
+export declare function toSearchableSpans<Span extends LightSpanRecord>(spans: Span[]): Array<Span & {
+    searchText: string;
+}>;
 /**
  * React Query `select` for the `{ traceId, spans }` payload returned by
  * `getTraceLight` and `getBranch`.