feat(dashboard-agent): validate chart queries when render_view runs

A chart block's TRQL query used to run only in the panel, after the turn, so a
bad query left a broken chart the model never learned about. render_view now
runs each chart query through the query API first and fails by name with the
query error, so the model fixes it in the same turn. The rows are discarded —
the panel stays the runner. Skipped when the turn has no delegated token or the
validation request itself fails.

Author: kathiekiwi

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

@@ -731,9 +731,10 @@ describe("watch wake narration", () => {
     });
 
     expect(calls.appendMessage).toHaveLength(2);
-    expect(
-      calls.appendMessage.map((call) => (call as { message: UIMessage }).message.id)
-    ).toEqual(["wake:watch:watch_1:fired", "wake:watch:watch_2:expired"]);
+    expect(calls.appendMessage.map((call) => (call as { message: UIMessage }).message.id)).toEqual([
+      "wake:watch:watch_1:fired",
+      "wake:watch:watch_2:expired",
+    ]);
   });
 });
 
@@ -1780,6 +1781,114 @@ describe("buildDashboardAgentTools", () => {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // render_view: a chart block's query is validated inside the turn
+  // -------------------------------------------------------------------------
+
+  const CHART_SPEC = {
+    blocks: [
+      {
+        type: "chart",
+        title: "Runs per hour",
+        query: "SELECT toStartOfHour(triggered_at) AS bucket, count() AS runs FROM runs",
+        period: "24h",
+        chartType: "line" as const,
+        xAxisColumn: "bucket",
+        yAxisColumns: ["runs"],
+      },
+    ],
+  };
+
+  const renderView = (ctx: Record<string, unknown>, spec: unknown) =>
+    (
+      buildDashboardAgentTools(ctx).render_view as {
+        execute: (i: unknown, o: unknown) => Promise<any>;
+      }
+    ).execute(spec, {});
+
+  const queryRequests = (requests: Array<{ url: string }>) =>
+    requests.filter((r) => r.url.endsWith("/api/v1/query"));
+
+  it("render_view fails with the chart query's own error, committing no blocks", async () => {
+    const fetchStub = stubFetch((url) => {
+      if (url.endsWith("/jwt")) return { body: { token: "jwt_1" } };
+      return { status: 400, body: { error: "Unknown column createdAt" } };
+    });
+    try {
+      const result = await renderView(ENV_CTX, {
+        blocks: [{ ...CHART_SPEC.blocks[0], query: "SELECT createdAt FROM runs" }],
+      });
+      expect(result.error).toContain("Unknown column createdAt");
+      expect(result.blocks).toBeUndefined();
+      expect(queryRequests(fetchStub.requests)).toHaveLength(1);
+    } finally {
+      fetchStub.restore();
+    }
+  });
+
+  it("render_view commits the chart when its query runs, validating it once", async () => {
+    const fetchStub = stubFetch((url, init) => {
+      if (url.endsWith("/jwt")) return { body: { token: "jwt_1" } };
+      // The validation runs the same window the panel will render.
+      expect(JSON.parse(String(init?.body))).toMatchObject({
+        scope: "environment",
+        period: "24h",
+      });
+      return { body: { results: [{ bucket: "2026-01-01T00:00:00Z", runs: 1 }] } };
+    });
+    try {
+      // The rows aren't embedded in the block — the panel stays the runner.
+      await expect(renderView(ENV_CTX, CHART_SPEC)).resolves.toEqual({ blocks: CHART_SPEC.blocks });
+      expect(queryRequests(fetchStub.requests)).toHaveLength(1);
+    } finally {
+      fetchStub.restore();
+    }
+  });
+
+  it("render_view commits the chart when the validation request itself fails", async () => {
+    const fetchStub = stubFetch((url) => {
+      if (url.endsWith("/jwt")) return { body: { token: "jwt_1" } };
+      throw new Error("ECONNREFUSED");
+    });
+    try {
+      await expect(renderView(ENV_CTX, CHART_SPEC)).resolves.toEqual({ blocks: CHART_SPEC.blocks });
+    } finally {
+      fetchStub.restore();
+    }
+  });
+
+  it("render_view skips chart validation when the turn carries no delegated token", async () => {
+    const fetchStub = stubFetch(() => ({ status: 400, body: { error: "never asked" } }));
+    try {
+      await expect(renderView({}, CHART_SPEC)).resolves.toEqual({ blocks: CHART_SPEC.blocks });
+      expect(fetchStub.requests).toEqual([]);
+    } finally {
+      fetchStub.restore();
+    }
+  });
+
+  it("render_view never runs a query for non-chart blocks", async () => {
+    const fetchStub = stubFetch(() => ({ status: 400, body: { error: "never asked" } }));
+    try {
+      const blocks = [
+        {
+          type: "diagnosis",
+          runId: "run_abc123",
+          summary: "The task threw because the order had no line items.",
+          category: "user_code_error",
+          likelyCause: "processOrder throws when items is empty.",
+          confidence: "high",
+          evidence: [{ type: "error", detail: "Error: order has no items" }],
+          nextSteps: ["Validate the payload before triggering."],
+        },
+      ];
+      await expect(renderView(ENV_CTX, { blocks })).resolves.toEqual({ blocks });
+      expect(fetchStub.requests).toEqual([]);
+    } finally {
+      fetchStub.restore();
+    }
+  });
+
   it("get_current_page returns the turn's structured page context", async () => {
     const pageContext = {
       page: { kind: "run" as const, runId: "run_1", status: "FAILED", taskId: "send-receipt" },

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

@@ -637,7 +637,7 @@ 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 — but the panel runs it AFTER your turn, so a broken query becomes a broken chart you never see. Column names are snake_case and the runs time column is triggered_at (not created_at); when unsure of a column, check get_query_schema before charting.
+- 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 — render_view runs the query to check it and fails with the error if it's broken, so read that message and render again. Column names are snake_case and the runs time column is triggered_at (not created_at); when unsure of a column, check get_query_schema before charting.
 - 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.

internal-packages/dashboard-agent/src/tools.ts

@@ -17,6 +17,7 @@ import {
   type ParsedTriggerUri,
   type ViewBlockInput,
 } from "@internal/dashboard-agent-contracts";
+import { logger } from "@trigger.dev/sdk";
 import { tool, type ToolSet } from "ai";
 import {
   askSupportSchema,
@@ -116,6 +117,13 @@ export type InvestigationsCapability = {
 
 type FetchResult = { ok: true; data: unknown } | { ok: false; status: number };
 
+// A query POST outcome, split by blame: "query" is the server rejecting the TRQL
+// itself (a 4xx carrying a message the model can act on), "transport" is the
+// request or the server breaking. Chart validation only fails a render on "query".
+type QueryPostResult =
+  | { ok: true; rows: Array<Record<string, unknown>> }
+  | { ok: false; kind: "query" | "transport"; error: string };
+
 async function apiGet(origin: string, path: string, token: string): Promise<FetchResult> {
   const res = await fetch(`${origin}${path}`, {
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
@@ -548,6 +556,74 @@ export function buildDashboardAgentTools(ctx: DashboardAgentToolContext): ToolSe
     return withEnvJwt((jwt) => apiGet(origin, path, jwt), unauthorizedGet);
   }
 
+  /**
+   * Run a TRQL query against the query API. A POST, so it can't use envApiGet —
+   * same JWT cache and same one-shot re-exchange on a 401, spelled out here.
+   * `null` means there is no current environment. Shared by the run_query tool
+   * and chart-block validation, so both see the same window and the same errors.
+   */
+  async function postQuery(
+    query: string,
+    period: string | undefined
+  ): Promise<QueryPostResult | null> {
+    const attempt = await withEnvJwt<{ res: Response } | { error: string }>(
+      async (jwt) => {
+        try {
+          return {
+            res: await fetch(`${origin}/api/v1/query`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${jwt}`,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+              },
+              body: JSON.stringify({ query, scope: "environment", period, format: "json" }),
+            }),
+          };
+        } catch (error) {
+          return { error: `Query request failed: ${(error as Error).message}` };
+        }
+      },
+      (result) => "res" in result && result.res.status === 401
+    );
+    if (!attempt) return null;
+    if ("error" in attempt) return { ok: false, kind: "transport", error: attempt.error };
+    const res = attempt.res;
+    // The route returns 400 with { error } for invalid TRQL; surface it so the
+    // model can fix the query rather than the turn dying.
+    const data = (await res.json().catch(() => ({}))) as { results?: unknown; error?: string };
+    if (!res.ok) {
+      return {
+        ok: false,
+        kind: res.status >= 500 ? "transport" : "query",
+        error: data.error ?? `Query failed (status ${res.status}).`,
+      };
+    }
+    return {
+      ok: true,
+      rows: Array.isArray(data.results) ? (data.results as Array<Record<string, unknown>>) : [],
+    };
+  }
+
+  /**
+   * The query error a chart block's query produced, or null when it's fine — or
+   * when we can't tell. Validation is a tripwire, not a gate: with no delegated
+   * token (e.g. a wake or action turn) or on a broken request we skip it rather
+   * than block the render.
+   */
+  async function validateChartQuery(
+    query: string,
+    period: string | undefined
+  ): Promise<string | null> {
+    const result = await postQuery(query, period);
+    if (!result || result.ok) return null;
+    if (result.kind === "transport") {
+      logger.warn("Skipped chart query validation", { error: result.error });
+      return null;
+    }
+    return result.error;
+  }
+
   /**
    * One request to the watch-alerts routes, as the user (delegated token).
    *
@@ -1253,39 +1329,11 @@ export function buildDashboardAgentTools(ctx: DashboardAgentToolContext): ToolSe
     run_query: tool({
       ...runQuerySchema,
       execute: async ({ query, period }) => {
-        // POST, so it can't use envApiGet — same JWT cache and same one-shot
-        // re-exchange on a 401, spelled out around the query request.
-        const attempt = await withEnvJwt<{ res: Response } | { error: string }>(
-          async (jwt) => {
-            try {
-              return {
-                res: await fetch(`${origin}/api/v1/query`, {
-                  method: "POST",
-                  headers: {
-                    Authorization: `Bearer ${jwt}`,
-                    "Content-Type": "application/json",
-                    Accept: "application/json",
-                  },
-                  body: JSON.stringify({ query, scope: "environment", period, format: "json" }),
-                }),
-              };
-            } catch (error) {
-              return { error: `Query request failed: ${(error as Error).message}` };
-            }
-          },
-          (result) => "res" in result && result.res.status === 401
-        );
-        if (!attempt) return { error: "No current environment is available to query." };
-        if ("error" in attempt) return attempt;
-        const res = attempt.res;
-        // The route returns 400 with { error } for invalid TRQL; surface it so
-        // the model can fix the query rather than the turn dying.
-        const data = (await res.json().catch(() => ({}))) as { results?: unknown; error?: string };
-        if (!res.ok) return { error: data.error ?? `Query failed (status ${res.status}).` };
-        const rows = Array.isArray(data.results)
-          ? (data.results as Array<Record<string, unknown>>)
-          : [];
+        const result = await postQuery(query, period);
+        if (!result) return { error: "No current environment is available to query." };
+        if (!result.ok) return { error: result.error };
         const cap = 200;
+        const rows = result.rows;
         return { rows: rows.slice(0, cap), rowCount: rows.length, truncated: rows.length > cap };
       },
     }),
@@ -1349,9 +1397,27 @@ export function buildDashboardAgentTools(ctx: DashboardAgentToolContext): ToolSe
     // An `investigation` block is the exception — see `renderInvestigations`: it
     // is the one progressive block, so the executor (not the model) owns its
     // identity and commits each revision before the block reaches the transcript.
+    //
+    // A `chart` block gets its query run here first. The panel runs that query
+    // after the turn, so a broken one would leave a chart the model never learns
+    // failed; validating now turns it into a named failure the model can fix in
+    // this turn. The rows are thrown away — the panel stays the runner and the
+    // renderer — and the double execution is near-free thanks to ClickHouse's
+    // 30s query cache.
     render_view: tool({
       ...renderViewSchema,
-      execute: async (view) => renderInvestigations(view.blocks, view.investigationId),
+      execute: async (view) => {
+        for (const block of view.blocks) {
+          if (block.type !== "chart") continue;
+          const queryError = await validateChartQuery(block.query, block.period);
+          if (queryError) {
+            return {
+              error: `The chart query failed: ${queryError}. Fix the query — column names are snake_case — and render the chart again.`,
+            };
+          }
+        }
+        return renderInvestigations(view.blocks, view.investigationId);
+      },
     }),
 
     get_report: tool({