feat: the Watch feature, re-applied on top of the extracted base

Revert of the extraction commit (19d6625): restores schedule_watch, the
tick loop, wake delivery with fenced claims, the expiry sweep, watch
alerts, the watches table and migrations, and all UI surfaces.

Author: kathiekiwi

.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.

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

@@ -1,14 +1,27 @@
 import type { SuggestedPrompt } from "@internal/dashboard-agent-contracts";
-import { useCallback, useMemo, useState } from "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";
 import { useDashboardAgentOpenRequests } from "./dashboardAgentOpenRequest";
+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
@@ -32,20 +45,47 @@ export function DashboardAgent({
   // 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);
-    // The panel unmounts on close, so a stale request would re-apply on the next
-    // open instead of restoring the last chat.
-    if (!next) setRequestedMessage(undefined);
+    // 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) => {
@@ -55,6 +95,67 @@ export function DashboardAgent({
     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]
+  );
+
   // ⌘J toggles the panel. Opening mounts the composer, which focuses itself, so
   // the shortcut lands you in the text field. Enabled inside inputs too, so the
   // same keystroke closes the panel while you're typing in it.
@@ -71,8 +172,8 @@ export function DashboardAgent({
   useDashboardAgentOpenRequests({ enabled: hasAccess, openWith, setOpen: setPanelOpen });
 
   const context = useMemo(
-    () => ({ open, setOpen: setPanelOpen, openWith }),
-    [open, setPanelOpen, openWith]
+    () => ({ open, setOpen: setPanelOpen, openWith, unreadWakes }),
+    [open, setPanelOpen, openWith, unreadWakes]
   );
 
   if (!hasAccess) {
@@ -95,7 +196,9 @@ export function DashboardAgent({
             <DashboardAgentPanel
               onClose={() => setPanelOpen(false)}
               requestedMessage={requestedMessage}
+              openChatRequest={openChatRequest}
               promotedPrompt={promotedPrompt}
+              onChatRead={markChatRead}
             />
           </ResizablePanel>
         </ResizablePanelGroup>

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

@@ -1,7 +1,7 @@
 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 type { AgentIntent, SuggestedPrompt, 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";
@@ -16,6 +16,29 @@ import { appendRunFilters, pendingNavigateIntents } from "./navigate-target";
 import type { AgentPageContext } from "./page-context-types";
 import { useAgentMessageQuota } from "./useAgentMessageQuota";
 import { useTriggerUriResolver } from "./useTriggerUriResolver";
+import { WatchChips, type WatchChip } from "./WatchChips";
+
+/**
+ * The message a card's watch button sends on the user's behalf. Written the way
+ * the user would ask, so the transcript reads as a request the agent then
+ * confirms (via schedule_watch), not as UI state that changed silently.
+ */
+function watchRequestText(spec: WatchSpec): string {
+  const note = "note" in spec && spec.note ? spec.note.trim() : "";
+  if (note) return `Watch this for me — tell me when ${note}.`;
+  switch (spec.kind) {
+    case "backlog_drain":
+      return `Watch this for me — tell me when the ${spec.queue} backlog drains.`;
+    case "run_start":
+      return `Watch this for me — tell me when run ${spec.runId} starts.`;
+    case "run_finished":
+      return `Watch this for me — tell me when run ${spec.runId} finishes.`;
+    case "error_recurrence":
+      return `Watch this for me — ping me if error ${spec.fingerprint} comes back.`;
+    case "health_recovery":
+      return "Watch this for me — tell me when health is back to normal.";
+  }
+}
 
 // The persisted session for a chat: the session-scoped token plus the stream
 // cursor. Resuming with `lastEventId` is what stops the agent's `.out` stream
@@ -59,7 +82,9 @@ export function DashboardAgentChat({
   streaming,
   prefill,
   promotedPrompt,
+  watches,
   pagePaths,
+  onCancelWatch,
   onTurnSettled,
   onActivityChange,
 }: {
@@ -87,9 +112,12 @@ export function DashboardAgentChat({
   // The product-controlled promoted chip, from the feature flag. Only used for
   // the suggested prompts on an empty chat.
   promotedPrompt?: SuggestedPrompt;
+  // This chat's active watches, from the panel's history load.
+  watches: WatchChip[];
   /** Host-resolved dashboard paths for settings-page footer actions. */
   pagePaths?: Record<string, string>;
-  /** A turn settled — tell the panel to refresh its history list. */
+  onCancelWatch: (watchId: string) => void;
+  /** A watch was created — tell the panel to re-read the chips. */
   onTurnSettled: () => void;
   /**
    * Whether a turn is in flight, for the History list's row marker. Only this
@@ -263,8 +291,11 @@ export function DashboardAgentChat({
   );
 
   // What a card's action does. An `ask` goes back into the conversation as the
-  // user's own question, so the click is visible in the transcript rather than
-  // happening silently.
+  // user's own question — and so does a `watch`: the click becomes a visible
+  // request ("Watch this for me…") and the agent answers it with schedule_watch,
+  // confirming in its own words and offering an email alert when none is set up.
+  // A silent POST would be cheaper, but a watch the transcript never mentions
+  // reads as nothing having happened.
   //
   // `propose_fix` is reserved and must never be executed.
   const handleIntent = useCallback(
@@ -273,6 +304,9 @@ export function DashboardAgentChat({
         case "ask":
           submit(intent.prompt);
           return;
+        case "watch":
+          submit(watchRequestText(intent.spec));
+          return;
         case "navigate":
           void goTo(intent);
           return;
@@ -324,6 +358,15 @@ export function DashboardAgentChat({
 
   return (
     <>
+      {/* What this chat is watching, at the top of the panel: a watch outcome
+          arrives in the transcript unprompted, so the chips are what explain
+          where those messages will come from. */}
+      {/* Chips are an offer to cancel, so only live watches get one; the full
+          list still flows to the messages for the wake banner's tone. */}
+      <WatchChips
+        watches={watches.filter((watch) => watch.status === "active")}
+        onCancel={onCancelWatch}
+      />
       {/* A cold-start chat mounts with no messages and a first message about to
           be sent, so the prompts would flash for a frame before the transcript
           replaced them. Gate on that pending send. */}
@@ -342,6 +385,7 @@ export function DashboardAgentChat({
           onDismissError={clearError}
           onIntent={handleIntent}
           pagePaths={pagePaths}
+          watches={watches}
           resolveUri={resolveUri}
         />
       )}

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

@@ -7,31 +7,40 @@ import { FormButtons } from "~/components/primitives/FormButtons";
 import { Paragraph } from "~/components/primitives/Paragraph";
 import { Spinner } from "~/components/primitives/Spinner";
 import { AgentList, AgentListRow, AgentListRowAction } from "./list-row";
+import type { WatchChip } from "./WatchChips";
 
 // Date fields arrive as strings over the loader's JSON.
 export type DashboardAgentChat = {
   id: string;
   title: string;
   lastMessageAt: string | null;
+  /** The chat's active watches, for the panel's chip row. */
+  watches?: WatchChip[];
+  /** A watch resolved in this chat and the user hasn't opened it since. */
+  hasUnreadWake?: boolean;
+  /** The chat holds at least one active watch. */
+  hasActiveWatch?: boolean;
   /** The chat's latest investigation is still `in_progress`. */
   hasOpenInvestigation?: boolean;
 };
 
 /** Something is running in this chat. One per row, most immediate first. */
-type ChatProcess = "thinking" | "investigating";
+type ChatProcess = "thinking" | "investigating" | "watching";
 
 const PROCESS_LABELS: Record<ChatProcess, string> = {
   thinking: "Agent is thinking",
   investigating: "Investigation in progress",
+  watching: "Watch active",
 };
 
 /**
  * `thinking` outranks the rest: a turn in flight is the thing that's about to
- * change, an investigation just sits there.
+ * change, an investigation or a watch just sits there.
  */
 function chatProcess(chat: DashboardAgentChat, isThinking: boolean): ChatProcess | null {
   if (isThinking) return "thinking";
   if (chat.hasOpenInvestigation) return "investigating";
+  if (chat.hasActiveWatch) return "watching";
   return null;
 }
 
@@ -44,12 +53,25 @@ function ProcessIcon({ process }: { process: ChatProcess }) {
       {process === "investigating" ? (
         <MagnifyingGlassIcon className="size-3.5" />
       ) : (
+        // Thinking and watching both spin — "something is going on here"; the
+        // hover title says which.
         <Spinner className="size-3.5" />
       )}
     </span>
   );
 }
 
+/**
+ * Chats with an unread wake go to the top — a watch that fired is the reason to
+ * open the panel at all. Everything else keeps the server's order (pinned first,
+ * then most recent), so this is a stable sort on one key.
+ */
+function unreadFirst(chats: DashboardAgentChat[]): DashboardAgentChat[] {
+  return [...chats].sort(
+    (a, b) => Number(b.hasUnreadWake ?? false) - Number(a.hasUnreadWake ?? false)
+  );
+}
+
 /** Units the row's age can be shown in. Months and years would read as "1.8mo" for
  *  eight weeks, which is worse than "8w" — weeks are the coarsest useful unit. */
 const AGE_UNITS = ["w", "d", "h", "m"] as const;
@@ -70,8 +92,8 @@ export function chatAge(lastMessageAt: string, now: number = Date.now()): string
 
 /**
  * The chat list, as the body of the header's title dropdown. Rows keep the
- * panel's list language (process icon, hover delete) — only the container
- * changed from a full panel view to a popover menu.
+ * panel's list language (unread dot, process icon, hover delete) — only the
+ * container changed from a full panel view to a popover menu.
  */
 export function DashboardAgentHistoryMenu({
   chats,
@@ -104,13 +126,14 @@ export function DashboardAgentHistoryMenu({
           </Paragraph>
         ) : (
           <AgentList>
-            {chats.map((chat) => {
+            {unreadFirst(chats).map((chat) => {
               const process = chatProcess(chat, chat.id === thinkingChatId);
               const age = chat.lastMessageAt ? chatAge(chat.lastMessageAt, now) : undefined;
               return (
                 <AgentListRow
                   key={chat.id}
                   label={chat.title}
+                  unread={chat.hasUnreadWake ?? false}
                   // null keeps the leading slot so every title starts at the
                   // same x whether or not this chat has a status.
                   status={process ? <ProcessIcon process={process} /> : null}