fix(webapp): send the agent wake signal to a browser that has never opened the panel

Author: kathiekiwi

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

@@ -20,7 +20,7 @@ import {
   writeAgentFullscreen,
 } from "./panel-layout";
 import { startWakePolling } from "./wake-poll";
-import { hasWatchActivity, subscribeWatchActivity } from "./watch-activity";
+import { shouldPollWakeFeed, subscribeWatchActivity } from "./watch-activity";
 import {
   showWatchWakesSummaryToast,
   showWatchWakeToast,
@@ -38,18 +38,22 @@ export function DashboardAgent({
   children,
   hasAccess = false,
   promotedPrompt,
+  /** From the page load: unread wakes waiting for this user, whatever this browser remembers. */
+  initialUnreadWakes = 0,
 }: {
   children: React.ReactNode;
   hasAccess?: boolean;
   promotedPrompt?: SuggestedPrompt;
+  initialUnreadWakes?: number;
 }) {
   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);
+  // 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(() => {
@@ -137,15 +141,23 @@ export function DashboardAgent({
     setWatchRequest((current) => ({ spec, seq: (current?.seq ?? 0) + 1 }));
   }, []);
 
-  // Nothing to be woken about means nothing to poll for. Once this browser has seen a watch it
-  // keeps polling, so a wake still reaches a tab that was open before the watch existed.
+  // Nothing to be woken about means nothing to poll for. The page load's unread count is the
+  // ungated signal; the browser's own memory of a watch starts the poll without a reload. Once
+  // either says yes this tab keeps polling, so a wake reaches a tab open before the watch existed.
   const [watching, setWatching] = useState(false);
   useEffect(() => {
-    if (hasWatchActivity(organization.id)) setWatching(true);
-    return subscribeWatchActivity(() => {
-      if (hasWatchActivity(organization.id)) setWatching(true);
-    });
-  }, [organization.id]);
+    const sync = () => {
+      if (
+        shouldPollWakeFeed({
+          serverUnreadWakes: initialUnreadWakes,
+          organizationId: organization.id,
+        })
+      )
+        setWatching(true);
+    };
+    sync();
+    return subscribeWatchActivity(sync);
+  }, [organization.id, initialUnreadWakes]);
 
   useEffect(() => {
     if (!hasAccess || !watching) return;

apps/webapp/app/components/dashboard-agent/watch-activity.test.ts

@@ -17,8 +17,13 @@ const windowStub = {
     void storageListeners.delete(listener),
 };
 
-const { forgetWatchActivity, hasWatchActivity, rememberWatchActivity, subscribeWatchActivity } =
-  await import("./watch-activity");
+const {
+  forgetWatchActivity,
+  hasWatchActivity,
+  rememberWatchActivity,
+  shouldPollWakeFeed,
+  subscribeWatchActivity,
+} = await import("./watch-activity");
 
 /** What another tab writing the key looks like here. */
 function otherTabWrote(organizationId: string) {
@@ -90,4 +95,21 @@ describe("watch activity", () => {
     expect(hasWatchActivity("org_0")).toBe(false);
     expect(hasWatchActivity("org_11")).toBe(true);
   });
+
+  describe("shouldPollWakeFeed", () => {
+    it("polls in a fresh browser the page load says has an unread wake", () => {
+      expect(shouldPollWakeFeed({ serverUnreadWakes: 1, organizationId: "org_1" })).toBe(true);
+    });
+
+    it("stays quiet when neither the page load nor this browser knows of anything", () => {
+      expect(shouldPollWakeFeed({ serverUnreadWakes: 0, organizationId: "org_1" })).toBe(false);
+    });
+
+    it("polls without a reload once this browser sees a watch", () => {
+      rememberWatchActivity("org_1");
+
+      expect(shouldPollWakeFeed({ serverUnreadWakes: 0, organizationId: "org_1" })).toBe(true);
+      expect(shouldPollWakeFeed({ serverUnreadWakes: 0, organizationId: "org_2" })).toBe(false);
+    });
+  });
 });

apps/webapp/app/components/dashboard-agent/watch-activity.ts

@@ -1,7 +1,8 @@
 /**
- * Which organizations this browser has seen agent watches in. The wake feed costs a request per
- * open tab per minute, so only a browser that knows a watch exists polls it — and once it knows,
- * it keeps polling. Shared through `localStorage`, so a watch created in one tab wakes the others.
+ * Which organizations this browser has seen agent watches in. This is an accelerator, not the
+ * gate: a watch created in this tab starts the poll without a reload. The ungated signal is the
+ * unread count the page load carries — see {@link shouldPollWakeFeed}.
+ * Shared through `localStorage`, so a watch created in one tab wakes the others.
  */
 
 const STORAGE_KEY = "tdev:dashboard-agent:watching";
@@ -56,6 +57,17 @@ export function forgetWatchActivity(organizationId: string): void {
   }
 }
 
+/**
+ * Whether this browser should poll the wake feed. `serverUnreadWakes` comes from the page load,
+ * so a fresh browser with an unread wake polls without ever opening the panel.
+ */
+export function shouldPollWakeFeed(params: {
+  serverUnreadWakes: number;
+  organizationId: string;
+}): boolean {
+  return params.serverUnreadWakes > 0 || hasWatchActivity(params.organizationId);
+}
+
 /** Fires when this browser learns of a watch, in this tab or — via `storage` — in another one. */
 export function subscribeWatchActivity(listener: () => void): () => void {
   listeners.add(listener);

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam/route.tsx

@@ -1,8 +1,10 @@
+import { countUnreadWatchWakes } from "@internal/dashboard-agent-db";
 import { Outlet, useLoaderData } from "@remix-run/react";
 import { redirect, type LoaderFunctionArgs } from "@remix-run/server-runtime";
 import { RouteErrorDisplay } from "~/components/ErrorDisplay";
 import { DashboardAgent } from "~/components/dashboard-agent/DashboardAgent";
 import { prisma } from "~/db.server";
+import { dashboardAgentDb } from "~/services/dashboardAgentDb.server";
 import { updateCurrentProjectEnvironmentId } from "~/services/dashboardPreferences.server";
 import { logger } from "~/services/logger.server";
 import { hasAdminDisplayAccess, requireUser } from "~/services/session.server";
@@ -96,19 +98,37 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
       })
     : null;
 
+  // One narrow read per page load, so the wake signal reaches a browser that has never opened
+  // the panel. The poll never asks for this — it costs nothing per tick.
+  let dashboardAgentUnreadWakes = 0;
+  if (hasDashboardAgentAccess) {
+    try {
+      dashboardAgentUnreadWakes = await countUnreadWatchWakes(dashboardAgentDb, {
+        organizationId: project.organization.id,
+        userId: user.id,
+      });
+    } catch (error) {
+      // The dashboard must load even when the agent's store doesn't answer.
+      logger.error("Failed to count dashboard agent wakes", { error });
+    }
+  }
+
   return {
     ...project,
     hasDashboardAgentAccess,
     promotedDashboardAgentPrompt,
+    dashboardAgentUnreadWakes,
   };
 };
 
 export default function Page() {
-  const { hasDashboardAgentAccess, promotedDashboardAgentPrompt } = useLoaderData<typeof loader>();
+  const { hasDashboardAgentAccess, promotedDashboardAgentPrompt, dashboardAgentUnreadWakes } =
+    useLoaderData<typeof loader>();
   return (
     <DashboardAgent
       hasAccess={hasDashboardAgentAccess}
       promotedPrompt={promotedDashboardAgentPrompt ?? undefined}
+      initialUnreadWakes={dashboardAgentUnreadWakes}
     >
       <Outlet />
     </DashboardAgent>