@mastra/playground-ui 68.0.0 → 69.0.0-alpha.1

package/dist/src/domains/dashboards/lib/plan-widget.d.ts

@@ -0,0 +1,390 @@
+import type { WidgetRequests, WidgetState } from '../widget-kind';
+import type { BlockedFields, DashboardEnvironment, PendingGate, WidgetGate } from './gate';
+import type { PreparedWidget } from './prepare-widget';
+import type { DashboardPageContext, DashboardResult } from './requests';
+/** A widget that parsed and shows at the page's scope. */
+export type ReadyPreparedWidget = Extract<PreparedWidget, {
+    ok: true;
+}>;
+export type WidgetPlan = 
+/** The server can't answer the widget: it renders nothing and sends nothing. */
+{
+    status: 'hidden';
+}
+/** The widget waits on, or can't apply, the page's aggregate gates: it sends nothing yet. */
+ | {
+    status: 'pending';
+    gate: PendingGate;
+} | {
+    status: 'ready';
+    page: DashboardPageContext;
+    blocked: BlockedFields;
+    /** Send first: their answers, passed back as `discovered`, decide `requests`. */
+    discover: WidgetRequests;
+    /** What the widget renders from; `undefined` slots aren't sent. */
+    requests: WidgetRequests;
+};
+/**
+ * The queries the page's gates apply to with `state` picked: the kind's `gatedQueries`, or every
+ * view's. A kind planning no requests fetches on its own, behind its own `ViewGate`, so the planner
+ * never holds it up.
+ */
+export declare function plannedQueries({ kind, views }: ReadyPreparedWidget, state: WidgetState): ({
+    name: string[];
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    distinctColumn?: "entityName" | "entityType" | "environment" | "executionSource" | "model" | "name" | "parentEntityName" | "parentEntityType" | "provider" | "resourceId" | "rootEntityName" | "rootEntityType" | "serviceName" | "threadId" | undefined;
+    source: "metrics";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    request: "aggregate";
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        traceIds?: string[] | undefined;
+        experimentIds?: string[] | undefined;
+        name?: string[] | undefined;
+        source?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        costUnit?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    } | undefined;
+} | {
+    name: string[];
+    groupBy: string[];
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    distinctColumn?: "entityName" | "entityType" | "environment" | "executionSource" | "model" | "name" | "parentEntityName" | "parentEntityType" | "provider" | "resourceId" | "rootEntityName" | "rootEntityType" | "serviceName" | "threadId" | undefined;
+    limit?: number | undefined;
+    orderDirection?: "ASC" | "DESC" | undefined;
+    source: "metrics";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    request: "breakdown";
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        traceIds?: string[] | undefined;
+        experimentIds?: string[] | undefined;
+        name?: string[] | undefined;
+        source?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        costUnit?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    } | undefined;
+} | {
+    name: string[];
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    distinctColumn?: "entityName" | "entityType" | "environment" | "executionSource" | "model" | "name" | "parentEntityName" | "parentEntityType" | "provider" | "resourceId" | "rootEntityName" | "rootEntityType" | "serviceName" | "threadId" | undefined;
+    groupBy?: string[] | undefined;
+    source: "metrics";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    request: "timeSeries";
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        traceIds?: string[] | undefined;
+        experimentIds?: string[] | undefined;
+        name?: string[] | undefined;
+        source?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        costUnit?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    } | undefined;
+} | {
+    name: string;
+    percentiles: number[];
+    source: "metrics";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    request: "percentiles";
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        traceIds?: string[] | undefined;
+        experimentIds?: string[] | undefined;
+        name?: string[] | undefined;
+        source?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        costUnit?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    } | undefined;
+} | {
+    scoreSource?: string | undefined;
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    source: "scores";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    scorerId?: string | undefined;
+    request: "aggregate";
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        scorerId?: string | string[] | undefined;
+        scoreSource?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        source?: string | undefined;
+    } | undefined;
+} | {
+    scoreSource?: string | undefined;
+    groupBy: string[];
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    source: "scores";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    scorerId?: string | undefined;
+    request: "breakdown";
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        scorerId?: string | string[] | undefined;
+        scoreSource?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        source?: string | undefined;
+    } | undefined;
+} | {
+    scoreSource?: string | undefined;
+    aggregation: "avg" | "count" | "count_distinct" | "last" | "max" | "min" | "sum";
+    groupBy?: string[] | undefined;
+    source: "scores";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    scorerId?: string | undefined;
+    request: "timeSeries";
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        scorerId?: string | string[] | undefined;
+        scoreSource?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        source?: string | undefined;
+    } | undefined;
+} | {
+    scoreSource?: string | undefined;
+    percentiles: number[];
+    source: "scores";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+    scorerId?: string | undefined;
+    request: "percentiles";
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    filters?: {
+        traceId?: string | undefined;
+        spanId?: string | undefined;
+        entityType?: import("@mastra/core/storage").EntityType | undefined;
+        entityName?: string | undefined;
+        entityVersionId?: string | undefined;
+        parentEntityVersionId?: string | undefined;
+        rootEntityVersionId?: string | undefined;
+        userId?: string | undefined;
+        organizationId?: string | undefined;
+        experimentId?: string | undefined;
+        serviceName?: string | undefined;
+        environment?: string | undefined;
+        parentEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        parentEntityName?: string | undefined;
+        rootEntityType?: import("@mastra/core/storage").EntityType | undefined;
+        rootEntityName?: string | undefined;
+        resourceId?: string | undefined;
+        runId?: string | undefined;
+        sessionId?: string | undefined;
+        threadId?: string | undefined;
+        requestId?: string | undefined;
+        executionSource?: string | undefined;
+        tags?: string[] | undefined;
+        scorerId?: string | string[] | undefined;
+        scoreSource?: string | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+        source?: string | undefined;
+    } | undefined;
+} | {
+    where?: import("@mastra/core/storage").TraceQueryPredicate | undefined;
+    groupBy?: string[] | undefined;
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    measures: ("cost.avg" | "cost.sum" | "count" | "duration.avg" | "duration.max" | "duration.min" | "duration.p50" | "duration.p90" | "duration.p95" | "duration.p99" | "errorCount" | "errorRate" | "timeToFirstChunk.avg" | "timeToFirstChunk.count" | "timeToFirstChunk.max" | "timeToFirstChunk.min" | "timeToFirstChunk.p50" | "timeToFirstChunk.p90" | "timeToFirstChunk.p95" | "timeToFirstChunk.p99" | "timeToFirstToken.avg" | "timeToFirstToken.count" | "timeToFirstToken.max" | "timeToFirstToken.min" | "timeToFirstToken.p50" | "timeToFirstToken.p90" | "timeToFirstToken.p95" | "timeToFirstToken.p99" | "tokens.cached.avg" | "tokens.cached.sum" | "tokens.input.avg" | "tokens.input.sum" | "tokens.output.avg" | "tokens.output.sum" | "tokens.reasoning.avg" | "tokens.reasoning.sum" | "tokens.total.avg" | "tokens.total.sum" | `countDistinct.${string}`)[];
+    having?: import("@mastra/core/storage").TraceQueryScalarPredicate | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    limit?: number | undefined;
+    source: "traceAggregate";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+} | {
+    where?: import("@mastra/core/storage").TraceQueryScalarPredicate | undefined;
+    groupBy?: string[] | undefined;
+    interval?: "15m" | "1d" | "1h" | "1m" | "5m" | undefined;
+    measures: ("cost.avg" | "cost.sum" | "count" | "duration.avg" | "duration.max" | "duration.min" | "duration.p50" | "duration.p90" | "duration.p95" | "duration.p99" | "errorCount" | "errorRate" | "timeToFirstChunk.avg" | "timeToFirstChunk.count" | "timeToFirstChunk.max" | "timeToFirstChunk.min" | "timeToFirstChunk.p50" | "timeToFirstChunk.p90" | "timeToFirstChunk.p95" | "timeToFirstChunk.p99" | "timeToFirstToken.avg" | "timeToFirstToken.count" | "timeToFirstToken.max" | "timeToFirstToken.min" | "timeToFirstToken.p50" | "timeToFirstToken.p90" | "timeToFirstToken.p95" | "timeToFirstToken.p99" | "tokens.cached.avg" | "tokens.cached.sum" | "tokens.input.avg" | "tokens.input.sum" | "tokens.output.avg" | "tokens.output.sum" | "tokens.reasoning.avg" | "tokens.reasoning.sum" | "tokens.total.avg" | "tokens.total.sum" | `countDistinct.${string}`)[];
+    having?: import("@mastra/core/storage").TraceQueryScalarPredicate | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    limit?: number | undefined;
+    source: "spanAggregate";
+    id?: string | undefined;
+    compare?: "previousWindow" | undefined;
+})[];
+/** Whether the queries the widget shows with `state` picked can run on the page `env` describes. */
+export declare const preparedGate: (prepared: ReadyPreparedWidget, env: DashboardEnvironment, state: WidgetState) => WidgetGate;
+/**
+ * What a widget sends, worked out from plain data and nothing else: the page `env`, the user's
+ * `state`, and the answers so far to its `discover` requests. Call it once without `discovered`,
+ * send `discover`, then again with their answers for the full `requests`; a host sending both at
+ * once (as `DashboardRenderer` does) re-plans as the answers arrive.
+ */
+export declare function planWidget(prepared: ReadyPreparedWidget, env: DashboardEnvironment, state: WidgetState, discovered?: (DashboardResult | undefined)[]): WidgetPlan;

package/dist/src/domains/dashboards/lib/requests.d.ts

@@ -39,6 +39,9 @@ type Call = {
 } | {
     method: 'getScorePercentiles';
     args: Args<'getScorePercentiles'>;
+} | {
+    method: 'listScores';
+    args: Args<'listScores'>;
 };
 /** One call a dashboard query makes, with the args it sends. */
 export type DashboardRequest = Call & {
@@ -56,6 +59,17 @@ export type DashboardAnswer = {
         data: Answers[M];
     };
 }[DashboardRequestMethod];
+/**
+ * Where a request's answer stands, as plain data: what a widget renders from, whoever fetched it.
+ * `isLoading` has no answer yet; `isRefetching` has one and is fetching it again.
+ */
+export type DashboardResult = {
+    data?: DashboardAnswer;
+    isLoading: boolean;
+    isRefetching: boolean;
+    isError: boolean;
+    error?: unknown;
+};
 type TraceWhere = NonNullable<AggregateTracesArgs['where']>;
 type SpanWhere = NonNullable<AggregateSpansArgs['where']>;
 /** What the page adds to every widget's query: its frozen window and its filter bar. */
@@ -72,6 +86,12 @@ export type DashboardRequestOptions = {
     /** The bucket size, for a query that doesn't set its own. Unset sends the query as written. */
     interval?: Interval;
 };
+/**
+ * The query with the page's filter bar ANDed in, as `buildRequest` applies it, but without the time
+ * window: trace and span predicates joined with `and`, metrics and scores filters intersected.
+ * `'unsatisfiable'` when the filters contradict, so nothing can match.
+ */
+export declare function pageQuery(query: DashboardQuery, page: DashboardPageContext): DashboardQuery | 'unsatisfiable';
 /**
  * The request a query sends over `window`, the page's filters ANDed with the widget's: trace and span
  * predicates are joined with `and`; metrics and scores filters intersect (`intersectFilters`), and a
@@ -83,6 +103,8 @@ export declare function buildRequest(query: DashboardQuery, page: DashboardPageC
 export declare function sendsPreviousRequest(query: DashboardQuery): boolean;
 /** The previous window's request, sent last so the widget never waits on it. */
 export declare function buildPreviousRequest(query: DashboardQuery, page: DashboardPageContext, options: DashboardRequestOptions): DashboardRequest | undefined;
+/** What an unsatisfiable request answers: nothing matched. */
+export declare function emptyAnswer(method: DashboardRequestMethod): DashboardAnswer;
 /** Runs a request on the client; an unsatisfiable one answers empty without a call. */
 export declare function sendRequest(client: MastraClient, request: DashboardRequest): Promise<DashboardAnswer>;
 /**

package/dist/src/domains/dashboards/lib/scores.d.ts

@@ -1,6 +1,6 @@
 import type { DashboardQuery } from '@mastra/client-js';
 import type { BucketLabels } from '../../metrics/lib/bucket-labels';
-import type { DashboardAnswer } from './requests';
+import type { DashboardAnswer, DashboardPageContext, DashboardRequest } from './requests';
 export type Scorer = {
     scorerId: string;
     name: string;
@@ -15,6 +15,16 @@ export declare function discoveredScorers(scores: {
     scorerId: string;
     scorerName?: string;
 }[]): Scorer[];
+/**
+ * The range's most recent scores, read to find the scorers when the queries leave theirs out (the API
+ * can't list scorers); `undefined` when they name their own.
+ */
+export declare function scorerDiscoveryRequest(queries: DashboardQuery[], page: DashboardPageContext): DashboardRequest | undefined;
+/**
+ * The scorers to chart: the queries' own scorer, or, when they leave it out, every scorer among the
+ * discovery request's answer, as the Scores card finds them.
+ */
+export declare function scorersOf(queries: DashboardQuery[], discovery: DashboardAnswer | undefined): Scorer[];
 /** The query for one scorer: its own scorer if it names one, else `scorerId`. */
 export declare const withScorer: (query: DashboardQuery | undefined, scorerId: string) => DashboardQuery | undefined;
 /**

package/dist/src/domains/dashboards/lib/timeseries.d.ts

@@ -2,7 +2,7 @@ import type { DashboardQuery } from '@mastra/client-js';
 import { z } from 'zod/v4';
 import type { BucketLabels } from '../../metrics/lib/bucket-labels';
 import type { DashboardAnswer } from './requests';
-import type { ValueExpr } from './values';
+import type { LabelledValue, ValueExpr } from './values';
 export declare const timeseriesSeriesSchema: z.ZodObject<{
     dataKey: z.ZodString;
     label: z.ZodString;
@@ -110,6 +110,11 @@ export declare function shapeTimeseries({ options, responses, window, hasTraceQu
     window: Window;
     hasTraceQueries: boolean;
 }): ShapedTimeseries;
+/**
+ * The numbers an alert could watch: each series over the range (its `rangeTotal`, else its value),
+ * then the card's total when it is an expression.
+ */
+export declare function timeseriesAlertValues(options: TimeseriesOptions): LabelledValue[];
 /**
  * What the schema can't say: query ids the view has, bucketed queries that leave their interval to the
  * chart's grid, refs that pick one of the percentiles their query asks for, and refs that pick one group

package/dist/src/domains/dashboards/lib/values.d.ts

@@ -43,6 +43,11 @@ export type ValueExpr = ValueRef | {
     coalesce: ValueExpr[];
 };
 export declare const valueExprSchema: z.ZodType<ValueExpr>;
+/** A number a view shows, under the name it shows it by: what a Create alert button lists. */
+export type LabelledValue = {
+    label: string;
+    value: ValueExpr;
+};
 export declare const VALUE_FORMATS: readonly ['count', 'usd', 'duration', 'percent', 'score'];
 export declare const formatSchema: z.ZodEnum<{
     count: "count";

package/dist/src/domains/dashboards/widget-kind.d.ts

@@ -1,8 +1,13 @@
-import type { DashboardWidget, DashboardWidgetView } from '@mastra/client-js';
+import type { DashboardQuery, DashboardWidget, DashboardWidgetView } from '@mastra/client-js';
 import type { ComponentType } from 'react';
 import type { z } from 'zod/v4';
 import type { ChartCardProps } from '../metrics/components/chart-card';
 import type { DashboardScope, OnDashboardDrilldown } from './lib/definition';
+import type { BlockedFields, WidgetGate } from './lib/gate';
+import type { DashboardPageContext, DashboardRequest, DashboardResult } from './lib/requests';
+import type { ValueRef } from './lib/values';
+import type { MetricsCardDragHandleProps } from '../../ds/components/MetricsCard';
+import type { MetricsTableSort } from '../../ds/components/MetricsTable';
 /** A view whose options passed its kind's schema. */
 export type ResolvedView<Options> = DashboardWidgetView & {
     options: Options;
@@ -15,6 +20,101 @@ export type WidgetKindProps<Options> = {
     onDrilldown?: OnDashboardDrilldown;
     /** Where a chart card expands to; see `DashboardExpand`. */
     expand?: DashboardExpand;
+    /** A grip to drag the widget by, shown left of its title: the host is arranging the dashboard. */
+    dragHandle?: MetricsCardDragHandleProps;
+    /** The widget's pin button, shown with its card's actions: the host can pin widgets. */
+    pin?: WidgetPin;
+    /** The card's Create alert button, for the open view: the host can turn views into alerts. */
+    alert?: DashboardAlert;
+    /** Whether the widget's queries can run on the page, and their page context once they can. */
+    gate: ShownGate;
+    /** What figures are compared against, e.g. `vs previous 24h`. */
+    comparisonLabel: string;
+    /** Display name for a project id, when the page spans several projects. */
+    projectLabel?: (projectId: string) => string;
+    /** What the user picked on the widget, held by the host. */
+    state: WidgetState;
+    /** Called with the whole next state when the user picks a view, sorts, or compares. */
+    onStateChange: (next: WidgetState) => void;
+    /** Answers to the kind's `discover` requests, in order. */
+    discovered: (DashboardResult | undefined)[];
+    /** Answers to the kind's `requests`, in order. */
+    results: (DashboardResult | undefined)[];
+    /** Asks the host to send the failed requests again. */
+    onRetry: () => void;
+};
+/** What a card's Create alert button watches: its open view, with the page's filters applied. */
+export type DashboardAlertTarget = {
+    widget: DashboardWidget;
+    view: DashboardWidgetView;
+    /**
+     * The view's queries with the page's filter bar ANDed in (`pageQuery`). They carry no time window:
+     * the alert picks its own. As authored, so a scores query may lack `scorerId` (the card reads
+     * every scorer); the host has to pick one or disable the button.
+     */
+    queries: DashboardQuery[];
+    /**
+     * Each distinct number the view shows, read straight from one query: a series, column or KPI, or,
+     * for one combining several (a ratio, a sum), each part. Same order as the view's options.
+     */
+    sources: DashboardAlertSource[];
+};
+/** One number a view reads from one query, as a single alert could watch it. */
+export type DashboardAlertSource = {
+    /** The series, column or KPI it belongs to; a part of a combined value adds its query and ref. */
+    label: string;
+    /** The query, with the page's filters applied, as in `queries`. */
+    query: DashboardQuery;
+    /** Which of the query's numbers: a measure, a field, a percentile, or only some groups. */
+    ref: DashboardAlertRef;
+};
+export type DashboardAlertRef = Omit<ValueRef, 'query'>;
+/** Where the button opens the host's alert editor, or why the view can't become an alert. */
+export type DashboardAlertAction = {
+    href: string;
+} | {
+    disabled: string;
+};
+/**
+ * How a host turns a card's open view into an alert. `action` returns one action for the whole card,
+ * `undefined` for no button, or an array aligned with `target.sources`: one action per source
+ * (`undefined` leaves it out). A card with several sources the host can alert on opens a menu of them.
+ * Links render through `LinkComponent`.
+ */
+export type DashboardAlert = {
+    action: (target: DashboardAlertTarget) => DashboardAlertAction | (DashboardAlertAction | undefined)[] | undefined;
+    LinkComponent: NonNullable<ChartCardProps['LinkComponent']>;
+};
+/** A widget's gate when it shows: waiting on, or ready to send, its requests. */
+export type ShownGate = Exclude<WidgetGate, {
+    status: 'hidden';
+}>;
+/**
+ * What the user picked on a widget: the open view, and a table's sort and the value column its
+ * % Change compares. Unset fields take the widget's defaults.
+ */
+export type WidgetState = {
+    view?: number;
+    sort?: MetricsTableSort;
+    compared?: string;
+};
+/** What a kind plans its requests from, once its gate is ready. */
+export type WidgetPlanContext<Options> = {
+    widget: DashboardWidget;
+    views: WidgetKindProps<Options>['views'];
+    page: DashboardPageContext;
+    blocked: BlockedFields;
+    state: WidgetState;
+};
+/** A kind's requests, in the order its answers come back; `undefined` slots aren't sent. */
+export type WidgetRequests = (DashboardRequest | undefined)[];
+/** A widget's pinned state, as the host holds it, and the call that asks the host to change it. */
+export type WidgetPin = {
+    isPinned: boolean;
+    /** Called with the state the user asked for. */
+    onPin: (isPinned: boolean) => void;
+    /** The widget's name in the button's label ("Pin Agent runs"), so each card's button is told apart. */
+    name: string;
 };
 /**
  * Where a chart widget expands to (a host's query page), as the Gateway Overview's cards do: the card
@@ -27,7 +127,9 @@ export type DashboardExpand = {
 };
 /**
  * One kind of widget, self-contained: the renderer only looks it up by name, checks each view's
- * options against `optionsSchema`, and renders `component`.
+ * options against `optionsSchema`, sends what `discover` then `requests` plan, and renders
+ * `component` with the answers. A kind planning neither sends nothing; its component may still fetch
+ * on its own (`ViewGate`, `useDashboardRequests`), but then only `DashboardRenderer` can host it.
  */
 export type WidgetKind<Options = unknown> = {
     kind: string;
@@ -35,6 +137,20 @@ export type WidgetKind<Options = unknown> = {
     optionsSchema: z.ZodType<Options>;
     /** Further problems with a view, e.g. options naming a query the view doesn't have. */
     issues?: (view: ResolvedView<Options>) => string[];
+    /**
+     * Shows the widget even when a page filter can't apply to some of its queries: its views say so
+     * on their own, checking `blocked` (a table's tabs).
+     */
+    partial?: boolean;
+    /**
+     * The queries the page's gates check, given what the user picked. Defaults to every view's, so
+     * pick only the views the widget shows: a closed view's trace query mustn't hide an open metrics one.
+     */
+    gatedQueries?: (views: WidgetPlanContext<Options>['views'], state: WidgetState) => DashboardQuery[];
+    /** Requests whose answers decide what `requests` asks (the scorers to chart, a table's opening tab). */
+    discover?: (ctx: WidgetPlanContext<Options>) => WidgetRequests;
+    /** The requests the widget renders from, given the answers to `discover`. */
+    requests?: (ctx: WidgetPlanContext<Options>, discovered: (DashboardResult | undefined)[]) => WidgetRequests;
     component: ComponentType<WidgetKindProps<Options>>;
 };
 /** Keeps a kind's options type while it joins a list of kinds of different options. */

package/dist/src/domains/knowledge/components/KnowledgePageDetail.d.ts

@@ -1,5 +1,10 @@
 import type { ReactNode } from 'react';
 import type { KnowledgePageActivityPayload, KnowledgeNotePayload, KnowledgePagePayload, KnowledgePinPayload } from '../pageTypes';
+export declare function KnowledgeDetailSection({ label, count, children, }: {
+    label: string;
+    count?: number;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /** One note: who wrote it and when, its text with `[[mentions]]` linked when the page is known, and the scopes it is stamped to. */
 export declare function KnowledgeNoteItem({ note, pagesById, onPageClick, highlighted, itemRef, showPage, compact, }: {
     note: KnowledgeNotePayload;
@@ -21,7 +26,8 @@ export declare function KnowledgeNoteItem({ note, pagesById, onPageClick, highli
  *
  * Paged lists take a `…More` slot the host fills with the next page's loader.
  */
-export declare function KnowledgePageDetail({ page, notes, pin, pagesById, onPageClick, highlightMentionOf, ancestors, mentionedBy, notesMore, childPages, activity, }: {
+export declare function KnowledgePageDetail({ page, notes, pin, pagesById, onPageClick, highlightMentionOf, ancestors, mentionedBy, notesMore, childPages, activity, compact, }: {
+    compact?: boolean;
     page: KnowledgePagePayload;
     notes: KnowledgeNotePayload[];
     pin?: KnowledgePinPayload;