feat(webapp): tell the user later — the dashboard agent's Watch

"Tell me when this run finishes", "ping me if that error comes back". A watch
checks on its own cadence, reports once, and stops within 24 hours. The user
confirms a pre-filled card, so nothing starts behind their back; the answer
lands in the chat, and by email if they asked for it.

Restores the feature this branch's base PR set aside, unchanged: the card and
chips, the wake banner and toast, the unread badge, the checks for runs, queues,
errors and health, the batch scheduler and its backstops, the alert channel and
its email, and the agent's schedule_watch tool with the prompt that governs it.

Author: kathiekiwi

.server-changes/dashboard-agent.md

@@ -7,6 +7,8 @@ Meet the dashboard agent: a chat in every environment that answers questions abo
 
 **Investigate** on a failed run, an error, a backed-up queue or a run that hasn't started gets you a worked-through answer — what happened, why, and how to fix it, with every claim linked to the runs, errors and deploys behind it.
 
+**Watch…** on a run, queue, error or the health report tells you when things change: a run finishes, a queue clears or grows past a number you pick, an error comes back, an environment recovers. The answer arrives in the chat and, if you want, by email, Slack or webhook — and the agent can look into bad news on its own. A watch reaches you on any browser you sign in from, without opening the chat first.
+
 The health report reads the same everywhere — dashboard, terminal, editor. A very long chat keeps working: the agent summarises the earlier part and carries on. The agent's replies no longer show images.
 
 A sample of conversations is scored automatically so the agent keeps getting better. Only the score and a one-line summary are kept, never your messages, data or code, and we can switch it off for your organization on request.

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

@@ -1,11 +1,14 @@
-import type { SuggestedPrompt } from "@internal/dashboard-agent-contracts";
+import type { SuggestedPrompt, WatchSpec } from "@internal/dashboard-agent-contracts";
 import { useLocation } from "@remix-run/react";
 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 { useShortcutKeys } from "~/hooks/useShortcutKeys";
 import { DashboardAgentPanel } from "./DashboardAgentPanel";
 import { DashboardAgentProvider, TOGGLE_PANEL_SHORTCUT } from "./dashboardAgentLauncher";
@@ -16,18 +19,68 @@ import {
   readAgentFullscreen,
   writeAgentFullscreen,
 } from "./panel-layout";
+import { startWakePolling } from "./wake-poll";
+import { shouldPollWakeFeed, subscribeWatchActivity } from "./watch-activity";
+import {
+  showWatchWakesSummaryToast,
+  showWatchWakeToast,
+  WAKE_TOAST_MAX_INDIVIDUAL,
+  type WatchWake,
+} from "./WatchWakeToast";
+
+const TOASTED_WAKES_STORAGE_KEY = "tdev:dashboard-agent:toasted-wakes";
+
+// Shorter than the poll interval, so a stuck request is dropped before the next tick.
+const UNREAD_REQUEST_TIMEOUT_MS = 30_000;
 
 /** `hasAccess` is a UI gate only; the resource routes enforce the same check server-side. */
 export function DashboardAgent({
   children,
   hasAccess = false,
   promotedPrompt,
+  /** From the page load: unread wakes waiting for this user, whatever this browser remembers. */
+  initialUnreadWakes = 0,
+  /** Also from the page load: a watch is running, so a wake can still arrive in this tab. */
+  hasActiveWatches = false,
 }: {
   children: React.ReactNode;
   hasAccess?: boolean;
   promotedPrompt?: SuggestedPrompt;
+  initialUnreadWakes?: number;
+  hasActiveWatches?: boolean;
 }) {
+  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);
+  // Seeded from the page load, so the launcher dot is right before the first poll answers.
+  const [unreadWakes, setUnreadWakes] = useState(initialUnreadWakes);
+  const toastedWakes = useRef(new Set<string>());
+  // The toast source is recent deliveries, not unread, so the dedupe must survive a reload.
+  useEffect(() => {
+    try {
+      const raw = window.localStorage.getItem(TOASTED_WAKES_STORAGE_KEY);
+      if (raw) for (const id of JSON.parse(raw) as string[]) toastedWakes.current.add(id);
+    } catch {
+      // Storage unavailable; the in-memory dedupe still applies.
+    }
+  }, []);
+  const rememberToasted = useCallback((watchId: string) => {
+    toastedWakes.current.add(watchId);
+    try {
+      // Newest ids only, so the key can't grow unbounded.
+      window.localStorage.setItem(
+        TOASTED_WAKES_STORAGE_KEY,
+        JSON.stringify([...toastedWakes.current].slice(-50))
+      );
+    } catch {
+      // Same as the read.
+    }
+  }, []);
+  // A wake in the on-screen chat toasts but must not light the dot.
+  const visibleChat = useRef<string | null>(null);
   // Read lazily so SSR always renders the side panel.
   const [fullscreen, setFullscreen] = useState(readAgentFullscreen);
 
@@ -53,24 +106,130 @@ export function DashboardAgent({
   const [requestedMessage, setRequestedMessage] = useState<
     { text: string; seq: number } | undefined
   >(undefined);
+  // `seq` so the same chat can be asked for twice.
+  const [openChatRequest, setOpenChatRequest] = useState<
+    { chatId: string; seq: number } | undefined
+  >(undefined);
+  const [watchRequest, setWatchRequest] = useState<{ spec: WatchSpec; seq: number } | undefined>(
+    undefined
+  );
 
   const setPanelOpen = useCallback((next: boolean) => {
     setOpen(next);
     // Pending requests must be dropped or a stale one re-applies on the next open.
     if (!next) {
+      visibleChat.current = null;
       setFullscreen(false);
       writeAgentFullscreen(false);
       setRequestedMessage(undefined);
+      setOpenChatRequest(undefined);
+      setWatchRequest(undefined);
     }
   }, []);
 
+  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 }));
   }, []);
 
+  const openWithWatch = useCallback((spec: WatchSpec) => {
+    setOpen(true);
+    setWatchRequest((current) => ({ spec, seq: (current?.seq ?? 0) + 1 }));
+  }, []);
+
+  // Nothing to be woken about means nothing to poll for. The page load's unread count and
+  // active-watch flag are the ungated signals; the browser's own memory of a watch starts the
+  // poll without a reload. Once any says yes this tab keeps polling, so a wake reaches a tab
+  // that was open before the watch existed.
+  const [watching, setWatching] = useState(false);
+  useEffect(() => {
+    const sync = () => {
+      if (
+        shouldPollWakeFeed({
+          serverUnreadWakes: initialUnreadWakes,
+          serverHasActiveWatches: hasActiveWatches,
+          organizationId: organization.id,
+        })
+      )
+        setWatching(true);
+    };
+    sync();
+    return subscribeWatchActivity(sync);
+  }, [organization.id, initialUnreadWakes, hasActiveWatches]);
+
+  useEffect(() => {
+    if (!hasAccess || !watching) return;
+
+    let cancelled = false;
+    const load = async () => {
+      try {
+        // Bounded, so one stuck request can't hold the poll's in-flight guard.
+        const res = await fetch(`${actionPath}?unread=1`, {
+          signal: AbortSignal.timeout(UNREAD_REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) return;
+        const data = (await res.json()) as { unreadWakes?: number; wakes?: WatchWake[] };
+        if (cancelled) return;
+        // The wakes list carries read ones too, so only unread ones are subtracted.
+        const unreadInView = (data.wakes ?? []).filter(
+          (wake) => wake.unread && wake.chatId === visibleChat.current
+        ).length;
+        setUnreadWakes(Math.max(0, (data.unreadWakes ?? 0) - unreadInView));
+
+        const fresh = (data.wakes ?? []).filter((wake) => !toastedWakes.current.has(wake.watchId));
+        for (const wake of fresh) rememberToasted(wake.watchId);
+
+        if (fresh.length > WAKE_TOAST_MAX_INDIVIDUAL) {
+          showWatchWakesSummaryToast(fresh.length, () => setPanelOpen(true));
+        } else {
+          for (const wake of [...fresh].reverse()) {
+            showWatchWakeToast(wake, openChat);
+          }
+        }
+      } catch {
+        // Try again next tick.
+      }
+    };
+
+    const stop = startWakePolling({
+      load,
+      isHidden: () => document.hidden,
+      onVisibilityChange: (listener) => {
+        document.addEventListener("visibilitychange", listener);
+        return () => document.removeEventListener("visibilitychange", listener);
+      },
+    });
+
+    return () => {
+      cancelled = true;
+      stop();
+    };
+  }, [hasAccess, watching, actionPath, setPanelOpen, openChat]);
+
+  // Zeroes the dot right away; the poll restores the truth if another chat has one.
+  const markChatRead = useCallback(
+    async (chatId: string) => {
+      visibleChat.current = chatId;
+      setUnreadWakes(0);
+      const body = new FormData();
+      body.set("intent", "read");
+      body.set("chatId", chatId);
+      try {
+        await fetch(actionPath, { method: "POST", body });
+      } catch {
+        // Catches up on the next open.
+      }
+    },
+    [actionPath]
+  );
+
   // ⌘J is contextual: closed opens the panel, open starts a new chat. It never closes.
   useShortcutKeys({
     shortcut: TOGGLE_PANEL_SHORTCUT,
@@ -88,8 +247,8 @@ export function DashboardAgent({
   useDashboardAgentOpenRequests({ enabled: hasAccess, openWith, setOpen: setPanelOpen });
 
   const context = useMemo(
-    () => ({ open, setOpen: setPanelOpen, openWith }),
-    [open, setPanelOpen, openWith]
+    () => ({ open, setOpen: setPanelOpen, openWith, openWithWatch, unreadWakes }),
+    [open, setPanelOpen, openWith, openWithWatch, unreadWakes]
   );
 
   if (!hasAccess) {
@@ -118,8 +277,11 @@ export function DashboardAgent({
                 <DashboardAgentPanel
                   onClose={() => setPanelOpen(false)}
                   requestedMessage={requestedMessage}
+                  openChatRequest={openChatRequest}
+                  watchRequest={watchRequest}
                   newChatSeq={newChatSeq}
                   promotedPrompt={promotedPrompt}
+                  onChatRead={markChatRead}
                   isFullscreen={fullscreen}
                   onToggleFullscreen={toggleFullscreen}
                 />

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

@@ -1,7 +1,12 @@
 import { useChat } from "@ai-sdk/react";
 import type { UIMessage } from "@ai-sdk/react";
 import type { dashboardAgent } from "@internal/dashboard-agent";
-import type { AgentIntent, SuggestedPrompt } from "@internal/dashboard-agent-contracts";
+import {
+  isWatchRequestMessageId,
+  type AgentIntent,
+  type SuggestedPrompt,
+  type WatchSpec,
+} from "@internal/dashboard-agent-contracts";
 import { useNavigate } from "@remix-run/react";
 import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -14,7 +19,7 @@ import { DashboardAgentMessages, type TurnActivity } from "./DashboardAgentMessa
 import { MESSAGE_TOO_LARGE_ERROR } from "./message-limits";
 import { createTranscriptOrder, orderTranscript } from "./message-order";
 import { appendRunFilters } from "./navigate-target";
-import { pendingNavigateIntents } from "./pending-intents";
+import { pendingNavigateIntents, pendingWatchIntents } from "./pending-intents";
 import type { AgentPageContext } from "./page-context-types";
 import {
   fetchChatTranscript,
@@ -23,6 +28,7 @@ import {
 } from "./settled-transcript";
 import { useAgentMessageQuota } from "./useAgentMessageQuota";
 import { useTriggerUriResolver } from "./useTriggerUriResolver";
+import { WatchChips, type WatchChip } from "./WatchChips";
 
 // Resuming with `lastEventId` stops the `.out` stream replaying the previous turn.
 export type DashboardAgentSession = {
@@ -55,7 +61,12 @@ export function DashboardAgentChat({
   streaming,
   prefill,
   promotedPrompt,
+  watches,
   pagePaths,
+  watchCard,
+  appendedMessages,
+  onWatchIntent,
+  onCancelWatch,
   onTurnSettled,
   onActivityChange,
 }: {
@@ -75,7 +86,13 @@ export function DashboardAgentChat({
   // `seq` makes each request distinct so the same text can be sent twice.
   prefill?: { text: string; seq: number };
   promotedPrompt?: SuggestedPrompt;
+  watches: WatchChip[];
   pagePaths?: Record<string, string>;
+  watchCard?: React.ReactNode;
+  appendedMessages?: { messages: UIMessage[]; seq: number };
+  /** Nothing is persisted until the user submits the card. */
+  onWatchIntent?: (spec: WatchSpec) => void;
+  onCancelWatch: (watchId: string) => void;
   onTurnSettled: () => void;
   onActivityChange?: (chatId: string, activity: TurnActivity | null) => void;
 }) {
@@ -172,6 +189,20 @@ export function DashboardAgentChat({
   const activity: TurnActivity | null =
     status === "submitted" ? "thinking" : status === "streaming" ? "working" : null;
 
+  // Once per `seq`: the append is already persisted, so a replay would duplicate it.
+  // Ids are stable, so anything already in the transcript is skipped.
+  const appendedSeq = useRef<number | undefined>(undefined);
+  useEffect(() => {
+    if (!appendedMessages || appendedSeq.current === appendedMessages.seq) return;
+    appendedSeq.current = appendedMessages.seq;
+    setMessages((current) => {
+      const missing = appendedMessages.messages.filter(
+        (message) => !current.some((existing) => existing.id === message.id)
+      );
+      return missing.length === 0 ? current : [...current, ...missing];
+    });
+  }, [appendedMessages, setMessages]);
+
   const sentFirst = useRef(false);
   useEffect(() => {
     if (pendingFirstMessage && !sentFirst.current) {
@@ -192,7 +223,10 @@ export function DashboardAgentChat({
   );
 
   const retry = useCallback(() => {
-    const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
+    // A watch's consent record is a user message nobody typed, so retry skips it.
+    const lastUserMessage = [...messages]
+      .reverse()
+      .find((m) => m.role === "user" && !isWatchRequestMessageId(m.id));
     const text = lastUserMessage?.parts
       ?.filter((p): p is { type: "text"; text: string } => p.type === "text")
       .map((p) => p.text)
@@ -230,14 +264,17 @@ export function DashboardAgentChat({
         case "ask":
           submit(intent.prompt);
           return;
+        case "watch":
+          onWatchIntent?.(intent.spec);
+          return;
         case "navigate":
           void goTo(intent);
           return;
         default:
           console.warn(`Dashboard agent: unhandled intent "${intent.kind}"`);
       }
     },
-    [submit, goTo]
+    [submit, goTo, onWatchIntent]
   );
 
   // Seeded from the loaded transcript before first render, so history never re-navigates.
@@ -252,6 +289,17 @@ export function DashboardAgentChat({
     if (target) void goTo(target);
   }, [messages, goTo]);
 
+  const watchProposedRef = useRef<Set<string> | null>(null);
+  if (watchProposedRef.current === null) {
+    watchProposedRef.current = new Set();
+    pendingWatchIntents(initialMessages, watchProposedRef.current);
+  }
+  useEffect(() => {
+    const pending = pendingWatchIntents(messages, watchProposedRef.current!);
+    const proposed = pending.at(-1);
+    if (proposed) onWatchIntent?.(proposed.spec);
+  }, [messages, onWatchIntent]);
+
   const stop = useCallback(() => {
     transport.stopGeneration(chatId);
     aiStop();
@@ -286,6 +334,10 @@ export function DashboardAgentChat({
 
   return (
     <>
+      <WatchChips
+        watches={watches.filter((watch) => watch.status === "active")}
+        onCancel={onCancelWatch}
+      />
       {messages.length === 0 && !pendingFirstMessage ? (
         <DashboardAgentHero
           onSelect={submit}
@@ -301,9 +353,11 @@ export function DashboardAgentChat({
           onDismissError={clearError}
           onIntent={handleIntent}
           pagePaths={pagePaths}
+          watches={watches}
           resolveUri={resolveUri}
         />
       )}
+      {watchCard ? <div className="px-3 pb-2">{watchCard}</div> : null}
       {quota.kind === "reached" ? (
         <AgentUpgradeBlock
           limit={quota.limit}