Dashboard Agent: investigations, watches, alerts, and notifications

.changeset/report-health.md

@@ -0,0 +1,8 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Add the `get_report` MCP tool, a `trigger report` CLI command, and `GET /api/v1/reports/:key`, starting with the `health` report: a deterministic verdict on whether work is flowing, whether the runs that start are healthy, and whether telemetry is fresh — rendered as text with unicode sparklines (coloured in a terminal). Also adds a `report` MCP prompt, surfaced as a slash command in hosts that support prompts.
+
+Also: `trigger mcp` now always starts the server — the install wizard is gated behind `trigger mcp --install`. A TTY previously launched the wizard, so MCP hosts spawning the server over a PTY timed out.

.server-changes/agent-detail-metrics-layout.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+The agent detail page now matches the shared metrics-page layout: the time filter and pagination sit in a filter row at the top, the activity charts form a tile row beneath it, and the tabs and table flow below in a single page scroll, with the agent config panel as a resizable sidebar on the right.

.server-changes/dashboard-agent-first-turn-error.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+When the assistant fails to start its very first reply, the chat now shows an error you can retry instead of sitting empty.

.server-changes/dashboard-agent-investigate.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The dashboard agent can now investigate failures for you: click Investigate on a failed run, an error, or a backed-up queue and it gathers the evidence, tests a few hypotheses, and answers with what happened and how to fix it — every claim linked to the runs, errors, and deploys behind it. Available to organizations with the dashboard agent enabled.

.server-changes/dashboard-agent-watch-alerts.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Watches you set up with the dashboard agent can now alert you by email, Slack, or webhook when they fire. Pick the new "Dashboard agent watches" type on the Alerts page, and turn it off again from any alert email.

.server-changes/dashboard-agent-watches.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Ask the dashboard agent to tell you when something happens — a run starting or finishing, a backlog clearing, an error coming back, an environment recovering — and it messages you in the chat once it does. Each chat can wait on up to three things at a time, for up to 24 hours.

.server-changes/paginate-concurrency-keys-table.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+The concurrency keys table on a queue's page is now paginated, so queues with thousands of keys can page through all of them instead of only showing the top 50.

.server-changes/queue-metrics-api.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+You can now read a single queue's wait times, peak depth, throughput, and how often it was throttled over a time window from the API.

.server-changes/queue-metrics-dashboard.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+New Queue metrics & health dashboard (per-org opt-in): per-queue depth, throughput, concurrency, throttling and scheduling-delay charts, a per-queue detail view, and live queue stats. Queue concurrency limits set above the environment limit are now rejected instead of being silently capped.

.server-changes/remove-header-docs-buttons.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+The Docs button has been removed from page headers to reduce clutter. Documentation links remain available in context where they're most useful.

apps/webapp/.gitignore

@@ -7,6 +7,9 @@ node_modules
 /cypress/screenshots
 /cypress/videos
 
+# Output of `pnpm run agent-ui:screenshots`
+/screenshots
+
 /app/styles/tailwind.css
 
 # Ensure the .env symlink is not removed by accident
@@ -20,4 +23,6 @@ storybook-static
 
 /prisma/seed.js
 /prisma/populate.js
-.memory-snapshots
+.memory-snapshots
+# Heartbeat story mode for seed-agent-examples (degraded | calm)
+.agent-examples-heartbeat-mode

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

@@ -7,6 +7,7 @@ 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";
 
 // Render an agent "chart" block by running its TRQL query through the dashboard's
 // own /resources/metric endpoint (session-authed, returns rows + real column
@@ -25,6 +26,21 @@ type MetricResponse =
       };
     };
 
+// The chart block's schema (`chartBlockBodySchema` in
+// @internal/dashboard-agent-contracts) carries only `period` for the time window
+// — no scope, no explicit from/to, no height. So these are fixed here rather
+// than plumbed from the block. If the schema grows those fields, read them off
+// `block` instead of using these.
+const CHART_SCOPE = "environment"; // the panel is always open in one environment
+const CHART_FROM = null; // `period` is the only window the agent can ask for
+const CHART_TO = null;
+const CHART_HEIGHT_CLASS = "h-64"; // fits the panel at its default width
+
+// Query errors come from ClickHouse via the metric endpoint and can carry SQL
+// and schema detail, so the panel shows a fixed message and the real one goes to
+// the console for whoever is debugging.
+const CHART_ERROR_MESSAGE = "This chart's query couldn't run.";
+
 type ChartState =
   | { status: "loading" }
   | { status: "error"; error: string }
@@ -63,18 +79,19 @@ export function AgentChart({ block }: { block: ChartBlock }) {
         organizationId,
         projectId,
         environmentId,
-        scope: "environment",
+        scope: CHART_SCOPE,
         period: block.period ?? null,
-        from: null,
-        to: null,
+        from: CHART_FROM,
+        to: CHART_TO,
       }),
       signal: controller.signal,
     })
       .then(async (res) => (await res.json()) as MetricResponse)
       .then((data) => {
         if (controller.signal.aborted) return;
         if (!data.success) {
-          setState({ status: "error", error: data.error });
+          console.error("Dashboard agent chart query failed:", data.error);
+          setState({ status: "error", error: CHART_ERROR_MESSAGE });
         } else {
           setState({
             status: "ready",
@@ -86,7 +103,8 @@ export function AgentChart({ block }: { block: ChartBlock }) {
       })
       .catch((err) => {
         if (controller.signal.aborted) return;
-        setState({ status: "error", error: err?.message ?? "The query failed to run." });
+        console.error("Dashboard agent chart request failed:", err);
+        setState({ status: "error", error: CHART_ERROR_MESSAGE });
       });
     return () => controller.abort();
   }, [block.query, block.period, organizationId, projectId, environmentId]);
@@ -109,7 +127,7 @@ export function AgentChart({ block }: { block: ChartBlock }) {
           {block.title}
         </div>
       ) : null}
-      <div className="h-64 w-full p-2">
+      <div className={cn("w-full p-2", CHART_HEIGHT_CLASS)}>
         {state.status === "loading" ? (
           <div className="flex h-full items-center justify-center gap-2 text-xs text-text-dimmed">
             <Spinner className="size-3" />

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

@@ -1,11 +1,25 @@
-import { useState } from "react";
+import type { SuggestedPrompt } from "@internal/dashboard-agent-contracts";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   ResizableHandle,
   ResizablePanel,
   ResizablePanelGroup,
 } from "~/components/primitives/Resizable";
+import { useEnvironment } from "~/hooks/useEnvironment";
+import { useOrganization } from "~/hooks/useOrganizations";
+import { useProject } from "~/hooks/useProject";
 import { DashboardAgentPanel } from "./DashboardAgentPanel";
 import { DashboardAgentProvider } from "./dashboardAgentLauncher";
+import {
+  showWatchWakesSummaryToast,
+  showWatchWakeToast,
+  WAKE_TOAST_MAX_INDIVIDUAL,
+  type WatchWake,
+} from "./WatchWakeToast";
+
+// How often the closed panel asks whether a watch woke a chat. A wake is worth
+// noticing within a minute, and the count is one indexed query.
+const UNREAD_POLL_INTERVAL_MS = 60_000;
 
 /**
  * Mounts the dashboard agent in the env layout. Renders the page content
@@ -22,18 +36,135 @@ import { DashboardAgentProvider } from "./dashboardAgentLauncher";
 export function DashboardAgent({
   children,
   hasAccess = false,
+  promotedPrompt,
 }: {
   children: React.ReactNode;
   hasAccess?: boolean;
+  // The product-controlled promoted prompt chip, from the feature flag.
+  promotedPrompt?: SuggestedPrompt;
 }) {
+  const organization = useOrganization();
+  const project = useProject();
+  const environment = useEnvironment();
+  const actionPath = `/resources/orgs/${organization.slug}/projects/${project.slug}/env/${environment.slug}/dashboard-agent`;
+
   const [open, setOpen] = useState(false);
+  const [unreadWakes, setUnreadWakes] = useState(0);
+  // Wakes already toasted this session. Session-scoped on purpose: a wake that
+  // arrived overnight deserves the toast on the first poll after a reload, but a
+  // wake the user has already been shown (and maybe dismissed) must not come
+  // back every 60s while the chat stays unread.
+  const toastedWakes = useRef(new Set<string>());
+  // A request from `openWith`, handed to the panel. `seq` makes repeat requests
+  // with the same text distinct, so the panel can tell them apart.
+  const [requestedMessage, setRequestedMessage] = useState<
+    { text: string; seq: number } | undefined
+  >(undefined);
+  // A specific chat to open, from a wake toast. `seq` so the same chat can be
+  // asked for twice (a second wake in a chat the user has already left).
+  const [openChatRequest, setOpenChatRequest] = useState<
+    { chatId: string; seq: number } | undefined
+  >(undefined);
+
+  // Closing drops any pending request, so reopening the panel later doesn't
+  // replay text the user has moved on from.
+  const setPanelOpen = useCallback((next: boolean) => {
+    setOpen(next);
+    // Closing drops both pending requests: the panel unmounts, so a stale one
+    // would re-apply on the next open instead of restoring the last chat.
+    if (!next) {
+      setRequestedMessage(undefined);
+      setOpenChatRequest(undefined);
+    }
+  }, []);
+
+  // Open the panel on the chat a wake happened in. Without the chat id the panel
+  // would just restore whatever it had open last, which is rarely the one the
+  // toast is about.
+  const openChat = useCallback((chatId: string) => {
+    setOpen(true);
+    setOpenChatRequest((current) => ({ chatId, seq: (current?.seq ?? 0) + 1 }));
+  }, []);
+
+  const openWith = useCallback((text: string) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    setOpen(true);
+    setRequestedMessage((current) => ({ text: trimmed, seq: (current?.seq ?? 0) + 1 }));
+  }, []);
+
+  // The dot's poll, and the toast's. Runs only while the panel is CLOSED — an
+  // open panel shows the wake in the transcript, so polling then would only race
+  // the read marker. Both the interval and the on-close refresh come from this
+  // effect re-running on `open`.
+  useEffect(() => {
+    if (!hasAccess || open) return;
+
+    let cancelled = false;
+    const load = async () => {
+      try {
+        const res = await fetch(`${actionPath}?unread=1`);
+        if (!res.ok) return;
+        const data = (await res.json()) as { unreadWakes?: number; wakes?: WatchWake[] };
+        if (cancelled) return;
+        setUnreadWakes(data.unreadWakes ?? 0);
+
+        const fresh = (data.wakes ?? []).filter((wake) => !toastedWakes.current.has(wake.watchId));
+        for (const wake of fresh) toastedWakes.current.add(wake.watchId);
+
+        // A burst gets one summary toast: a stack of persistent toasts is a wall,
+        // not a notification.
+        if (fresh.length > WAKE_TOAST_MAX_INDIVIDUAL) {
+          showWatchWakesSummaryToast(fresh.length, () => setPanelOpen(true));
+        } else {
+          // Oldest first, so the newest wake ends up nearest the user.
+          for (const wake of [...fresh].reverse()) {
+            showWatchWakeToast(wake, openChat);
+          }
+        }
+      } catch {
+        // Offline or a hiccup — leave the dot as it is and try again next tick.
+      }
+    };
+
+    void load();
+    const interval = window.setInterval(load, UNREAD_POLL_INTERVAL_MS);
+    return () => {
+      cancelled = true;
+      window.clearInterval(interval);
+    };
+  }, [hasAccess, open, actionPath, setPanelOpen, openChat]);
+
+  // A chat the user is now looking at has no unread wakes. Zeroes the dot right
+  // away (the poll restores the truth on close if another chat still has one) and
+  // persists the read marker for the chat that's actually visible.
+  const markChatRead = useCallback(
+    async (chatId: string) => {
+      setUnreadWakes(0);
+      const body = new FormData();
+      body.set("intent", "read");
+      body.set("chatId", chatId);
+      try {
+        await fetch(actionPath, { method: "POST", body });
+      } catch {
+        // Not worth surfacing: the marker is caught up the next time the chat is
+        // opened.
+      }
+    },
+    [actionPath]
+  );
+
+  const context = useMemo(
+    () => ({ open, setOpen: setPanelOpen, openWith, unreadWakes }),
+    [open, setPanelOpen, openWith, unreadWakes]
+  );
 
   if (!hasAccess) {
     return <div className="h-full min-h-0">{children}</div>;
   }
 
   return (
-    <DashboardAgentProvider value={{ open, setOpen }}>
+    <DashboardAgentProvider value={context}>
       {open ? (
         <ResizablePanelGroup
           orientation="horizontal"
@@ -45,7 +176,13 @@ export function DashboardAgent({
           </ResizablePanel>
           <ResizableHandle id="dashboard-agent-handle" />
           <ResizablePanel id="dashboard-agent-panel" default="380px" min="320px" max="720px">
-            <DashboardAgentPanel onClose={() => setOpen(false)} />
+            <DashboardAgentPanel
+              onClose={() => setPanelOpen(false)}
+              requestedMessage={requestedMessage}
+              openChatRequest={openChatRequest}
+              promotedPrompt={promotedPrompt}
+              onChatRead={markChatRead}
+            />
           </ResizablePanel>
         </ResizablePanelGroup>
       ) : (