feat(agent): ranking charts name the winner in prose and carry action buttons

A superlative question is answered in words with the top item's name and
number; the chart illustrates. The chart block gains up to three actions
(ask — the user's own follow-up, or navigate with a canonical trigger://
target), rendered as buttons under the chart and wired through the
panel's existing intent handling. A navigate target is a plain string at
the input boundary and a non-parsing one costs the button, never the
tool call.

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/AgentChart.tsx

@@ -1,13 +1,16 @@
 import type { OutputColumnMetadata } from "@internal/clickhouse";
 import type { ChartBlock } from "@internal/dashboard-agent";
+import { isTriggerUri, type AgentIntent, type ChartAction } from "@internal/dashboard-agent-contracts";
 import { useEffect, useState } from "react";
 import { QueryResultsChart } from "~/components/code/QueryResultsChart";
 import type { ChartConfiguration } from "~/components/metrics/QueryWidget";
+import { Button } from "~/components/primitives/Buttons";
 import { Spinner } from "~/components/primitives/Spinner";
 import { useOptionalEnvironment } from "~/hooks/useEnvironment";
 import { useOptionalOrganization } from "~/hooks/useOrganizations";
 import { useOptionalProject } from "~/hooks/useProject";
 import { cn } from "~/utils/cn";
+import { ChatActionsRow } from "./chat-layout";
 
 // Render an agent "chart" block by running its TRQL query through the dashboard's
 // own /resources/metric endpoint (session-authed, returns rows + real column
@@ -51,7 +54,53 @@ type ChartState =
       timeRange?: { from: string; to: string };
     };
 
-export function AgentChart({ block }: { block: ChartBlock }) {
+/**
+ * The buttons under a ranking chart: act on the item the chart put on top.
+ *
+ * A card never navigates or asks on its own — it hands the block's intent to the
+ * host, which submits an `ask` as the user's next message and resolves a
+ * `navigate` before moving. Without an `onIntent` there is nothing to hand it to,
+ * so the row isn't rendered rather than showing dead buttons.
+ */
+export function ChartActions({
+  actions,
+  onIntent,
+}: {
+  actions: ChartAction[];
+  onIntent?: (intent: AgentIntent) => void;
+}) {
+  // A chart action's navigate target is a plain string at the contract boundary
+  // (the model may hold no canonical URI) — only targets that really parse
+  // become buttons, so a hallucinated URI costs a button, never a dead click.
+  const renderable = actions.filter(
+    (action) => action.intent.kind !== "navigate" || isTriggerUri(action.intent.target)
+  );
+  if (!onIntent || renderable.length === 0) return null;
+  return (
+    <div className="border-t border-grid-bright px-2 pb-2 pt-2">
+      <ChatActionsRow>
+        {renderable.map((action, i) => (
+          <Button
+            key={i}
+            // The first action is the one to take; the rest are alternatives.
+            variant={i === 0 ? "primary/small" : "secondary/small"}
+            onClick={() => onIntent(action.intent as AgentIntent)}
+          >
+            {action.label}
+          </Button>
+        ))}
+      </ChatActionsRow>
+    </div>
+  );
+}
+
+export function AgentChart({
+  block,
+  onIntent,
+}: {
+  block: ChartBlock;
+  onIntent?: (intent: AgentIntent) => void;
+}) {
   const organization = useOptionalOrganization();
   const project = useOptionalProject();
   const environment = useOptionalEnvironment();
@@ -147,6 +196,7 @@ export function AgentChart({ block }: { block: ChartBlock }) {
           />
         )}
       </div>
+      <ChartActions actions={block.actions ?? []} onIntent={onIntent} />
     </div>
   );
 }

apps/webapp/app/components/dashboard-agent/demo/components/DemoChartCard.tsx

@@ -6,10 +6,21 @@
  * the fixture rows directly. The frame (border, title strip, height) mirrors
  * `AgentChart` so the card reads identically in the panel.
  */
+import type { AgentIntent, ChartAction } from "@internal/dashboard-agent-contracts";
 import { QueryResultsChart } from "~/components/code/QueryResultsChart";
+import { ChartActions } from "../../AgentChart";
 import { demoChart } from "../fixtures/chart";
 
-export function DemoChartCard({ title = demoChart.title }: { title?: string }) {
+export function DemoChartCard({
+  title = demoChart.title,
+  actions,
+  onIntent,
+}: {
+  title?: string;
+  /** The row under the chart, when this chart ranks something. */
+  actions?: ChartAction[];
+  onIntent?: (intent: AgentIntent) => void;
+}) {
   return (
     <div className="overflow-hidden rounded-lg border border-border-bright bg-background-dimmed">
       {title ? (
@@ -25,6 +36,7 @@ export function DemoChartCard({ title = demoChart.title }: { title?: string }) {
           timeRange={demoChart.timeRange}
         />
       </div>
+      <ChartActions actions={actions ?? []} onIntent={onIntent} />
     </div>
   );
 }

apps/webapp/app/components/dashboard-agent/demo/fixtures/blocks.ts

@@ -13,7 +13,7 @@ import {
   type EnvelopedDiagnosisBlock,
   type ViewBlock,
 } from "@internal/dashboard-agent-contracts";
-import { demoId, DEMO_WORLD } from "../ids";
+import { demoId, demoRunsUri, DEMO_WORLD } from "../ids";
 
 const envelope = (id: string, revision = 0) => ({
   id: demoId(id),
@@ -105,6 +105,25 @@ export const demoChartBlock: EnvelopedChartBlock = {
   groupByColumn: "task_identifier",
   stacked: false,
   aggregation: "sum",
+  // The chart ranks the tasks; the buttons act on the one it put on top. The ask
+  // is phrased as the user's own follow-up, because that's what it becomes.
+  actions: [
+    {
+      label: `Investigate ${DEMO_WORLD.taskId}`,
+      intent: {
+        kind: "ask",
+        prompt: `Investigate the ${DEMO_WORLD.taskId} failures — why are they failing?`,
+      },
+    },
+    {
+      label: "See its failed runs",
+      intent: {
+        kind: "navigate",
+        target: demoRunsUri(),
+        filters: { tasks: [DEMO_WORLD.taskId], statuses: ["COMPLETED_WITH_ERROR"], period: "1d" },
+      },
+    },
+  ],
 };
 
 /**

apps/webapp/app/components/dashboard-agent/demo/ids.ts

@@ -49,6 +49,10 @@ const scope = { projectRef: DEMO_PROJECT_REF, environmentId: DEMO_ENVIRONMENT_ID
 // fixture URI is grammar-valid by construction — the contracts package, not the
 // fixture author, decides what a legal URI looks like.
 
+export function demoRunsUri(): TriggerUri {
+  return formatTriggerUri({ kind: "runs", ...scope });
+}
+
 export function demoRunUri(runId: string): TriggerUri {
   return formatTriggerUri({ kind: "run", ...scope, runId });
 }

apps/webapp/app/components/dashboard-agent/view-catalog.tsx

@@ -52,7 +52,7 @@ export function ViewBlocks({
           case "diagnosis":
             return <RunDiagnosisCard key={key} block={block} />;
           case "chart":
-            return <AgentChart key={key} block={block} />;
+            return <AgentChart key={key} block={block} onIntent={onIntent} />;
           // The one progressive block: revisions share the investigationId, so
           // latest-wins above keeps a single live card.
           case "investigation":

apps/webapp/app/routes/storybook.agent-ui/manifest.ts

@@ -197,6 +197,11 @@ export const MANIFEST: GallerySection[] = [
 
   // --- Chart card ----------------------------------------------------------
   { sectionId: "chart-with-data", title: "With canned rows", group: "chart" },
+  {
+    sectionId: "chart-with-actions",
+    title: "Ranking chart with actions on the top item",
+    group: "chart",
+  },
   { sectionId: "chart-empty", title: "Empty — no data to display", group: "chart" },
 
   // --- Watch chips ---------------------------------------------------------

apps/webapp/app/routes/storybook.agent-ui/route.tsx

@@ -647,6 +647,9 @@ const STATES: Record<string, React.ReactNode> = {
 
   // --- Chart card ---------------------------------------------------------
   "chart-with-data": <DemoChartCard />,
+  "chart-with-actions": (
+    <DemoChartCard actions={demoFixtures.demoChartBlock.actions ?? []} onIntent={noop} />
+  ),
   "chart-empty": <EmptyChartCard />,
 
   // --- Watch chips --------------------------------------------------------

internal-packages/dashboard-agent-contracts/src/blocks.test.ts

@@ -185,6 +185,61 @@ describe("model-facing input schema", () => {
   });
 });
 
+describe("chart actions", () => {
+  // A ranking chart answers "which task fails most" — the actions are what to do
+  // about the winner. Two kinds, both from the intent union.
+  const actions = [
+    {
+      label: "Investigate send-order-receipt",
+      intent: {
+        kind: "ask",
+        prompt: "Investigate the send-order-receipt failures — why are they failing?",
+      },
+    },
+    {
+      label: "See its failed runs",
+      intent: {
+        kind: "navigate",
+        target: "trigger://proj_abc/env_abc/runs",
+        filters: { tasks: ["send-order-receipt"], period: "1d" },
+      },
+    },
+  ];
+
+  it("parses a chart with actions", () => {
+    const parsed = viewBlockInputSchema.parse({ ...legacyChart, actions });
+    expect(parsed.type).toBe("chart");
+    expect(parsed.type === "chart" && parsed.actions).toHaveLength(2);
+    expect(viewBlockSchema.safeParse({ ...legacyChart, ...envelope, actions }).success).toBe(true);
+    expect(parseStoredViewBlock({ ...legacyChart, actions }).type).toBe("chart");
+  });
+
+  it("still parses a chart with no actions", () => {
+    expect(viewBlockInputSchema.safeParse(legacyChart).success).toBe(true);
+    expect(legacyViewBlockSchema.safeParse(legacyChart).success).toBe(true);
+  });
+
+  it("caps the row at three buttons", () => {
+    const fourth = { label: "One too many", intent: { kind: "ask", prompt: "And this?" } };
+    expect(
+      viewBlockInputSchema.safeParse({ ...legacyChart, actions: [...actions, fourth, fourth] })
+        .success
+    ).toBe(false);
+  });
+
+  it("accepts a non-canonical navigate target — the renderer drops it, the call survives", () => {
+    // The model can't always build a canonical URI, and a malformed target must
+    // cost one button rather than fail the whole render_view call. ChartActions
+    // filters non-parsing targets out at render time.
+    expect(
+      viewBlockInputSchema.safeParse({
+        ...legacyChart,
+        actions: [{ label: "Runs", intent: { kind: "navigate", target: "/runs?status=FAILED" } }],
+      }).success
+    ).toBe(true);
+  });
+});
+
 describe("report block", () => {
   it("round-trips a whole view model", () => {
     const parsed = reportBlockSchema.parse(reportBlock);

internal-packages/dashboard-agent-contracts/src/blocks.ts

@@ -27,6 +27,7 @@
  * and is rendered in transcript order.
  */
 import { evidenceRefSchema, evidenceSchema } from "./evidence.js";
+import { runFiltersSchema } from "./run-filters.js";
 import { triggerUriSchema } from "./trigger-uri.js";
 import { z } from "zod";
 
@@ -150,6 +151,42 @@ export const diagnosisBlockBodySchema = z.object({
 // chart
 // ---------------------------------------------------------------------------
 
+/**
+ * A button under a chart. The chart answers "which task failed most"; the
+ * actions are what to do about the winner — investigate it, or go look at its
+ * runs. The card only *emits* the intent; the host decides whether to honour it,
+ * the same rule every other intent follows.
+ */
+/**
+ * A chart action's intent. Mirrors `agentIntentSchema`, but the navigate
+ * `target` is a plain string at this boundary — the model can't always build a
+ * canonical URI (the grammar embeds ids it doesn't hold), and a malformed
+ * target must cost one button, not the whole tool call. The `render_view`
+ * executor drops navigate actions whose target isn't a valid trigger:// URI.
+ */
+const chartActionIntentSchema = z.union([
+  z.object({
+    kind: z.literal("ask"),
+    prompt: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("navigate"),
+    target: z.string().min(1),
+    filters: runFiltersSchema.optional(),
+  }),
+]);
+
+export const chartActionSchema = z.object({
+  label: z
+    .string()
+    .describe("The button text, naming the thing, e.g. 'Investigate send-order-receipt'."),
+  intent: chartActionIntentSchema.describe(
+    "What the button does. `ask` is the default and always works: phrase the user's own follow-up in their voice ('Investigate the send-order-receipt failures — why are they failing?'), and the click sends it as their next message. `navigate` takes them to the matching page — ONLY when you already hold a canonical `trigger://` URI for it (e.g. one a tool returned); an invalid target is silently dropped, so when in doubt use `ask`."
+  ),
+});
+
+export type ChartAction = z.infer<typeof chartActionSchema>;
+
 // The chart block carries the TRQL query (not the rows): the panel runs it
 // through the dashboard's own query execution + QueryResultsChart, so the chart
 // is live and matches the Query page exactly. The agent describes the chart with
@@ -197,6 +234,18 @@ export const chartBlockBodySchema = z.object({
     .enum(["sum", "avg", "count", "min", "max"])
     .optional()
     .describe("How to combine values that share an x point. Default sum."),
+  /**
+   * Optional and capped at three: a chart that ranks things gets a way to act on
+   * the winner. Older stored charts have no `actions` at all and must keep
+   * parsing, so this is additive and never required.
+   */
+  actions: z
+    .array(chartActionSchema)
+    .max(3)
+    .optional()
+    .describe(
+      "Optional buttons under the chart, at most 2-3. After a ranking or failures chart, give the top item an 'Investigate <name>' ask action, and a navigate action to the page that shows it (its filtered runs list, its error, its queue) when you have the target."
+    ),
 });
 
 // ---------------------------------------------------------------------------

internal-packages/dashboard-agent/src/tool-schemas.ts

@@ -634,7 +634,10 @@ Investigations:
 Answering with data and charts:
 - For questions about metrics, trends, counts, rates, costs, or "over time" / "by task" style aggregations, query the analytics data. First call get_query_schema (no table to list the tables, then a table name for its columns), then write a TRQL query. TRQL is SQL-style over ClickHouse: bucket time with toStartOfHour/toStartOfDay on the table's time column, produce one numeric column per series with countIf/sumIf, always include a time filter, and keep the result aggregated to a few dozen points.
 - To chart the answer, call render_view with a "chart" block containing the TRQL query itself plus chartType (line for trends over time, bar for categories), xAxisColumn, yAxisColumns, and groupByColumn when you split a single value column into series. The panel runs the query and renders it, so you don't have to run_query first just to chart.
-- Use run_query when you want to state specific numbers in prose, or to sanity-check a query before charting. If it returns an error, read the message and fix the query.`;
+- Use run_query when you want to state specific numbers in prose, or to sanity-check a query before charting. If it returns an error, read the message and fix the query.
+- A chart never answers alone. A superlative or ranking question — "which tasks fail most", "what's slowest", "which queue is busiest" — is answered IN PROSE, naming the winner and its number ("send-order-receipt — 3 of the 4 failures"); the chart illustrates that answer, it is not the answer. Run the query with run_query when you need the number to say it.
+- On a ranking or failures chart, give the top item buttons through the chart block's "actions": an ask action phrasing the user's own follow-up ("Investigate the send-order-receipt failures — why are they failing?"), plus a navigate action to the page that shows it (its filtered runs list, its error, its queue) when you hold a canonical trigger:// target for it. Two or three, never more.
+- Those buttons are not an offer to do the work: they sit next to a finished answer, and they never license "want me to drill into the top offender?" — asking to look is still banned.`;
 
 // Used when the current project has a connected GitHub repo: the base prompt
 // plus the source-reading tools and how to use them.