Merge branch 'feat/dashboard-agent-flows-watch' into feat/agent-storybook-gallery

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/navigate-target.test.ts

@@ -1,22 +1,39 @@
 import { describe, expect, it } from "vitest";
+import { getRunFiltersFromSearchParams } from "~/components/runs/v3/RunFilters";
 import { appendRunFilters, navigateDestination, sameOriginPath } from "./navigate-target";
 
 const RUNS_PATH = "/orgs/acme/projects/api/env/prod/runs";
 
+const FAILING = [
+  "COMPLETED_WITH_ERRORS",
+  "SYSTEM_FAILURE",
+  "CRASHED",
+  "EXPIRED",
+  "TIMED_OUT",
+  "INTERRUPTED",
+];
+
+/** What the runs page makes of a URL this module produced. */
+function pageReads(path: string) {
+  return getRunFiltersFromSearchParams(
+    new URLSearchParams(new URL(path, "https://x.invalid").search)
+  );
+}
+
 describe("appendRunFilters", () => {
   it("returns the path untouched with no filters", () => {
     expect(appendRunFilters(RUNS_PATH)).toBe(RUNS_PATH);
   });
 
   it("writes arrays as repeated params and keeps existing ones", () => {
     const result = appendRunFilters(`${RUNS_PATH}?query=payments`, {
-      statuses: ["FAILED", "CRASHED"],
+      statuses: ["COMPLETED_WITH_ERRORS", "CRASHED"],
       tasks: "send-email",
       period: "1d",
     });
 
     expect(result).toBe(
-      `${RUNS_PATH}?query=payments&statuses=FAILED&statuses=CRASHED&tasks=send-email&period=1d`
+      `${RUNS_PATH}?query=payments&statuses=COMPLETED_WITH_ERRORS&statuses=CRASHED&tasks=send-email&period=1d`
     );
   });
 
@@ -30,6 +47,51 @@ describe("appendRunFilters", () => {
     expect(appendRunFilters(RUNS_PATH, { search: "", rootOnly: false, tags: [] })).toBe(RUNS_PATH);
     expect(appendRunFilters(RUNS_PATH, { rootOnly: true })).toBe(`${RUNS_PATH}?rootOnly=true`);
   });
+
+  it("expands FAILED into the statuses the page calls failures", () => {
+    const result = appendRunFilters(RUNS_PATH, { statuses: ["FAILED"], period: "1d" });
+
+    expect(pageReads(result)).toEqual({ statuses: FAILING, period: "1d" });
+  });
+
+  it("takes the status the user said, however they cased it", () => {
+    expect(pageReads(appendRunFilters(RUNS_PATH, { statuses: "failed" }))).toEqual({
+      statuses: FAILING,
+    });
+  });
+
+  it("passes a page-native status through untranslated", () => {
+    const result = appendRunFilters(RUNS_PATH, { statuses: ["COMPLETED_SUCCESSFULLY"] });
+
+    expect(result).toBe(`${RUNS_PATH}?statuses=COMPLETED_SUCCESSFULLY`);
+    expect(pageReads(result)).toEqual({ statuses: ["COMPLETED_SUCCESSFULLY"] });
+  });
+
+  it("translates the other API status names the model borrows", () => {
+    expect(pageReads(appendRunFilters(RUNS_PATH, { statuses: ["QUEUED", "COMPLETED"] }))).toEqual({
+      statuses: ["PENDING", "COMPLETED_SUCCESSFULLY"],
+    });
+  });
+
+  it("drops a status the page cannot parse rather than losing every filter with it", () => {
+    const result = appendRunFilters(RUNS_PATH, { statuses: ["NONSENSE"], period: "1d" });
+
+    expect(result).toBe(`${RUNS_PATH}?period=1d`);
+    expect(pageReads(result)).toEqual({ period: "1d" });
+  });
+
+  // The page's parser has no `search`, and an unread param is only noise in the URL.
+  it("leaves search out of the URL", () => {
+    expect(appendRunFilters(RUNS_PATH, { search: "boom", period: "1d" })).toBe(
+      `${RUNS_PATH}?period=1d`
+    );
+  });
+
+  // Control: the untranslated URL is what the live failure looked like. One status the
+  // page cannot parse and it discards everything, the period included.
+  it("pins why translation is needed: raw FAILED wipes the whole filter set", () => {
+    expect(pageReads(`${RUNS_PATH}?statuses=FAILED&period=1d`)).toEqual({});
+  });
 });
 
 describe("navigateDestination", () => {
@@ -38,7 +100,10 @@ describe("navigateDestination", () => {
   it("routes a dashboard path and applies the intent's filters", () => {
     expect(
       navigateDestination({ path: RUNS_PATH, external: false }, { statuses: ["FAILED"] })
-    ).toEqual({ kind: "route", path: `${RUNS_PATH}?statuses=FAILED` });
+    ).toEqual({
+      kind: "route",
+      path: `${RUNS_PATH}?${FAILING.map((s) => `statuses=${s}`).join("&")}`,
+    });
   });
 
   it("never routes a source file, it leaves the dashboard", () => {

apps/webapp/app/components/dashboard-agent/navigate-target.ts

@@ -1,17 +1,69 @@
 // `trigger://` targets are resolved server-side in `resolveTriggerUri.server.ts`.
 import { type RunFilters } from "@internal/dashboard-agent-contracts";
+import { allTaskRunStatuses } from "~/components/runs/v3/TaskRunStatus";
 
 // Filter keys are the runs page's own URL params, except that the page reads these
 // bounds as epoch milliseconds while an intent carries ISO strings.
 const EPOCH_MS_KEYS = new Set(["from", "to"]);
 
+// The page's filter parser has no `search` param, so it would only clutter the URL.
+const UNSUPPORTED_KEYS = new Set(["search"]);
+
+type PageStatus = (typeof allTaskRunStatuses)[number];
+
+const PAGE_STATUSES = new Set<string>(allTaskRunStatuses);
+
+/** What a user means by "failed runs": every terminal status that is not a success or a cancel. */
+const FAILING_STATUSES = [
+  "COMPLETED_WITH_ERRORS",
+  "SYSTEM_FAILURE",
+  "CRASHED",
+  "EXPIRED",
+  "TIMED_OUT",
+  "INTERRUPTED",
+] as const satisfies readonly PageStatus[];
+
+/** Statuses the API (and so the model) uses that the runs page has never heard of. */
+const STATUS_ALIASES = {
+  FAILED: FAILING_STATUSES,
+  QUEUED: ["PENDING"],
+  COMPLETED: ["COMPLETED_SUCCESSFULLY"],
+  REATTEMPTING: ["RETRYING_AFTER_FAILURE"],
+  FROZEN: ["WAITING_TO_RESUME"],
+} as const satisfies Record<string, readonly PageStatus[]>;
+
+/**
+ * Statuses in the page's own vocabulary. One value it cannot parse makes it discard
+ * every filter — the period too — so anything unrecognized is dropped, not sent.
+ */
+function pageStatuses(values: readonly string[]): string[] {
+  const translated = new Set<string>();
+  for (const value of values) {
+    const status = value.trim().toUpperCase();
+    if (PAGE_STATUSES.has(status)) {
+      translated.add(status);
+      continue;
+    }
+    for (const alias of STATUS_ALIASES[status as keyof typeof STATUS_ALIASES] ?? []) {
+      translated.add(alias);
+    }
+  }
+  return [...translated];
+}
+
 export function appendRunFilters(path: string, filters?: RunFilters): string {
   if (!filters) return path;
   // A base is needed to parse a relative path; only pathname + search is used.
   const url = new URL(path, "https://dashboard.invalid");
 
   for (const [key, value] of Object.entries(filters)) {
     if (value === undefined || value === null || value === "") continue;
+    if (UNSUPPORTED_KEYS.has(key)) continue;
+    if (key === "statuses") {
+      const statuses = Array.isArray(value) ? value : [String(value)];
+      for (const status of pageStatuses(statuses)) url.searchParams.append(key, status);
+      continue;
+    }
     if (EPOCH_MS_KEYS.has(key)) {
       const epochMs = Date.parse(String(value));
       if (!Number.isNaN(epochMs)) url.searchParams.set(key, String(epochMs));

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

@@ -106,7 +106,8 @@ describe("every chat change goes through one door", () => {
     // The watch's own landing chat: without the claim, an earlier open still matches its seq.
     const submit = panel.slice(panel.indexOf("const submitWatch = useCallback("));
     const claim = submit.indexOf("claimChatSlot();");
-    const setActive = submit.indexOf("setActive({ chatId: data.chatId");
+    // Whitespace-tolerant: the formatter is free to wrap the call across lines.
+    const setActive = submit.search(/setActive\(\{\s*chatId:\s*data\.chatId/);
     expect(claim).toBeGreaterThan(-1);
     expect(setActive).toBeGreaterThan(claim);
   });

apps/webapp/app/services/dashboardAgentWatchToken.server.ts

@@ -97,7 +97,8 @@ const WATCH_BATCH_TOKEN_CLIENT = "dashboard-agent-watch-batch";
 
 /**
  * How long a chain's token lives. A chain has no deadline to pin it to, but it must still
- * expire; an expired one is self-healing via the re-arm backstop.
+ * expire. A chain whose token no longer verifies keeps ticking — a failed check is never a
+ * verdict — and gets a fresh token when the re-arm backstop starts the next epoch.
  */
 export const WATCH_BATCH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 

internal-packages/dashboard-agent-contracts/src/run-filters.ts

@@ -9,15 +9,16 @@ const stringOrStringArray = z.union([z.string(), z.array(z.string())]).optional(
 export const runFiltersSchema = z.object({
   tasks: stringOrStringArray,
   versions: stringOrStringArray,
-  statuses: stringOrStringArray,
+  statuses: stringOrStringArray.describe(
+    "Run statuses as the dashboard names them: PENDING_VERSION, DELAYED, PENDING, DEQUEUED, EXECUTING, WAITING_TO_RESUME, COMPLETED_SUCCESSFULLY, COMPLETED_WITH_ERRORS, TIMED_OUT, CRASHED, SYSTEM_FAILURE, CANCELED, EXPIRED. FAILED is accepted as shorthand for any failing status; anything else is ignored."
+  ),
   tags: stringOrStringArray,
   queues: stringOrStringArray,
   /** Relative window shorthand, e.g. "1h", "24h", "7d". */
   period: z.string().optional(),
   /** Absolute window bounds as ISO strings. */
   from: z.string().optional(),
   to: z.string().optional(),
-  search: z.string().optional(),
   rootOnly: z.boolean().optional(),
   batchId: z.string().optional(),
   scheduleId: z.string().optional(),

internal-packages/dashboard-agent/GUIDEBOOK.md

@@ -371,7 +371,9 @@ falls within one cadence is always due, so the final evaluation is never missed.
 The group's chain stops only when nothing is active **and** nothing is owed.
 
 A check that came back `unavailable` in a batch is recorded as an attempt rather
-than as a check, so the stall streak and the last-checked time survive it.
+than as a check, so the stall streak and the last-checked time survive it. If the
+batch check itself can't be read, nothing was looked at, so nothing is recorded —
+and the chain still reschedules, so the group keeps its cadence.
 
 A sweep (`dashboardAgentWatchSweep.server.ts`) is the backstop:
 

internal-packages/dashboard-agent/src/__snapshots__/prompt-prefix.test.ts.snap

@@ -283,7 +283,7 @@ export const navigateToSchema = tool({
           filters: runFiltersSchema
             .optional()
             .describe(
-              "Filters to apply to the runs list: tasks, statuses, versions, tags, queues, and a period like '1d'."
+              "Filters to apply to the runs list: tasks, statuses, versions, tags, queues, and a period like '1d'. Statuses must be the dashboard's own status names — see the field's own description."
             ),
         }),
         z.object({

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

@@ -59,7 +59,8 @@ export type WatchBatchTickDeps = {
 };
 
 export type WatchBatchTickResult = {
-  outcome: "ticked" | "stale";
+  // `unavailable`: the check phase itself couldn't run, so the group learned nothing.
+  outcome: "ticked" | "stale" | "unavailable";
   results: Array<{ watchId: string; outcome?: WatchTickOutcome; error?: string }>;
   rescheduled: boolean;
 };
@@ -92,7 +93,22 @@ export async function runWatchBatchTick(
   payload: WatchBatchTickPayload,
   deps: WatchBatchTickDeps
 ): Promise<WatchBatchTickResult> {
-  const response = await deps.checkBatch(payload);
+  let response: WatchBatchCheckResponse;
+  try {
+    response = await deps.checkBatch(payload);
+  } catch (error) {
+    // A check failure is never a verdict: the group learned nothing, so nothing is
+    // recorded — no watch was looked at — and the chain ticks on to try again.
+    logger.error("dashboard-agent watch batch check is unavailable; ticking on", {
+      environmentId: payload.environmentId,
+      cadenceMinutes: payload.cadenceMinutes,
+      epoch: payload.epoch,
+      tick: payload.tick,
+      error: (error as Error).message,
+    });
+    await scheduleNextBatchTick(payload, deps);
+    return { outcome: "unavailable", results: [], rescheduled: true };
+  }
 
   if (response.stale) {
     logger.info("dashboard-agent watch batch is stale; exiting", {
@@ -114,16 +130,7 @@ export async function runWatchBatchTick(
   // Before the rethrow below, so the chain survives a watch that keeps failing.
   let rescheduled = false;
   if (response.continues) {
-    const next = payload.tick + 1;
-    await deps.reschedule(
-      { ...payload, tick: next },
-      {
-        delay: `${payload.cadenceMinutes}m`,
-        // Keyed on the epoch too, so a re-armed chain can't collide with its
-        // predecessor's keys.
-        idempotencyKey: `watch-batch:${payload.environmentId}:${payload.cadenceMinutes}:${payload.epoch}:tick:${next}`,
-      }
-    );
+    await scheduleNextBatchTick(payload, deps);
     rescheduled = true;
   }
 
@@ -141,6 +148,24 @@ export async function runWatchBatchTick(
   return { outcome: "ticked", results, rescheduled };
 }
 
+// The successor's generation comes from this run's own, and rides in the idempotency
+// key, so a resumed or duplicated tick schedules the same successor once.
+async function scheduleNextBatchTick(
+  payload: WatchBatchTickPayload,
+  deps: WatchBatchTickDeps
+): Promise<void> {
+  const next = payload.tick + 1;
+  await deps.reschedule(
+    { ...payload, tick: next },
+    {
+      delay: `${payload.cadenceMinutes}m`,
+      // Keyed on the epoch too, so a re-armed chain can't collide with its
+      // predecessor's keys.
+      idempotencyKey: `watch-batch:${payload.environmentId}:${payload.cadenceMinutes}:${payload.epoch}:tick:${next}`,
+    }
+  );
+}
+
 /** One watch of a batch: each resolves in its own try, so a failure isolates. */
 async function resolveBatchEntry(
   payload: WatchBatchTickPayload,