fix(schedules): load live fields in schedule lists (#368)

## Problem

The schedules UI loads persisted schedule definitions first, then sends
one detail request per schedule to obtain live Temporal fields. In
authenticated deployments, failures in that detail-request fan-out leave
`next_action_times` empty without surfacing an error. As a result, valid
schedules disappear from Upcoming and "Skip next run" is unavailable
even though their Temporal clocks have future actions.

## Solution

- add an opt-in `include_live` query parameter to schedule listing
- enrich authorized rows with live Temporal fields using a concurrency
limit of 10
- keep the existing database-only list behavior as the default for
compatibility and performance
- have the UI request enriched lists and remove the per-schedule
detail-request fan-out
- surface a notice when an active schedule still lacks next-run data

## Test plan

- [x] Backend schedule service unit tests
- [x] Backend schedule authorization route unit tests
- [x] Frontend schedule hook tests
- [x] Frontend TypeScript typecheck
- [x] Frontend lint and formatting checks
- [x] Local smoke test confirms enriched lists return future action
times

Made with [Cursor](https://cursor.com)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR moves live Temporal field enrichment from a per-schedule
client-side fan-out to a single server-side batch operation gated by an
opt-in `include_live` query parameter. The previous approach silently
dropped schedules from the "Upcoming" view when any per-schedule detail
request failed in authenticated deployments.

- **Backend**: `list_schedules` now accepts `include_live=True`,
collects visible rows, then concurrently enriches up to
`MAX_LIVE_ENRICHMENT_ROWS` (200) via a semaphore-bounded
`asyncio.gather(return_exceptions=True)`; rows beyond the cap are
returned with `live_data_available=None` rather than a misleading
`False`. A new `live_data_available: bool | None` field on the response
schema distinguishes enrichment success, enrichment failure, and
enrichment not requested.
- **Frontend**: Both list hooks now pass `include_live: true` and
`staleTime: 30_000`, replacing the removed
`useAgentRunScheduleDetailsForItems` fan-out. The "Upcoming" tab shows a
targeted status notice when any non-paused schedule has
`live_data_available === false`, directing users to the Schedules tab
for definitions that are still intact.
- **Tests**: Four new service-layer tests cover the live path, semaphore
concurrency bound, fan-out cap via monkeypatch, and the guarantee that
all sibling tasks settle before re-raising an error.

<details><summary><h3>Confidence Score: 5/5</h3></summary>

Safe to merge — the change is opt-in (default include_live=False
preserves existing behavior), the fan-out ceiling and semaphore prevent
overload, and all previously identified issues have been addressed.

All three concerns from the prior review round (return_exceptions=True,
staleTime on enriched queries, live_data_available distinguishing
enrichment failures from genuinely empty schedules) were addressed. The
new logic is well-covered by four targeted service tests. The DB-only
default path is unchanged, and the include_live=True path degrades
gracefully per row rather than failing the whole request.

No files require special attention.
agentex/src/domain/services/agent_run_schedule_service.py carries the
most new logic but is thoroughly tested.
</details>

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| agentex/src/domain/services/agent_run_schedule_service.py | Core
enrichment logic: bounded gather with semaphore,
MAX_LIVE_ENRICHMENT_ROWS cap, return_exceptions=True, and
live_data_available tri-state field all implemented correctly |
| agentex/src/api/routes/agent_run_schedules.py | Adds include_live
query parameter with Annotated[bool, Query(...)] annotation and threads
it through to the use case |
| agentex/src/api/schemas/agent_run_schedules.py | Adds
live_data_available: bool | None field to AgentRunScheduleResponse with
correct nullable default and clear docstring |
| agentex-ui/hooks/use-agent-run-schedules.ts | Removes per-schedule
detail fan-out; both list hooks now pass include_live:true and
staleTime:30_000; AgentRunScheduleListItem export removed cleanly |
| agentex-ui/components/scheduled-tasks/scheduled-tasks-page.tsx |
Removes detailQueries fan-out; computes unavailableLiveDataCount from
live_data_available===false and shows a targeted status notice on the
upcoming tab |
| agentex-ui/lib/agent-run-schedules.ts | Adds live_data_available:
boolean | null to AgentRunSchedule type and normalizeAgentRunSchedule
with correct null coalescing |
| agentex/tests/unit/services/test_agent_run_schedule_service.py | Four
new tests cover include_live=True path, bounded concurrency, fan-out cap
(via monkeypatch), and waiting for all rows before re-raising — solid
coverage |
| agentex/tests/unit/api/test_agent_run_schedules_authz.py | Updates
authz route test to pass and assert include_live=True through the use
case call |
| agentex-ui/hooks/use-agent-run-schedules.test.tsx | New test verifies
the hook passes include_live:true and that live_data_available is
surfaced on the returned schedule object |
| agentex-ui/lib/schedule-utils.test.ts | Test fixtures updated to
include live_data_available: null to match the new field; no logic
changes |
| agentex/openapi.yaml | Adds include_live query parameter and
live_data_available response field to the OpenAPI spec; nullable boolean
uses anyOf correctly |
| agentex/src/domain/use_cases/agent_run_schedules_use_case.py | Minimal
pass-through change: adds include_live parameter to list_schedules and
forwards it to the service |

</details>

<details><summary><h3>Sequence Diagram</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant UI as ScheduledTasksPage
    participant Hook as useAgentRunSchedules
    participant API as GET /agents/{id}/schedules
    participant Svc as AgentRunScheduleService
    participant DB as Postgres
    participant T as Temporal (xN semaphore10)

    UI->>Hook: mount / staleTime expires
    Hook->>API: "?include_live=true&limit=50"
    API->>Svc: "list_schedules(include_live=True)"
    Svc->>DB: list_by_agent_id()
    DB-->>Svc: rows (all)
    Note over Svc: auth filter to visible_rows
    Note over Svc: live_rows = visible_rows[:200]
    par asyncio.gather semaphore 10
        Svc->>T: describe_schedule(id_1)
        T-->>Svc: ScheduleDescription
        Svc->>T: describe_schedule(id_2)
        T-->>Svc: ScheduleDescription or Exception
    end
    Note over Svc: live_data_available True or False per row
    Svc-->>API: AgentRunScheduleListResponse
    API-->>Hook: JSON run_schedules total
    Hook-->>UI: data staleTime 30s
    Note over UI: upcoming filter next_action_times not null
    Note over UI: notice if live_data_available is false
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant UI as ScheduledTasksPage
    participant Hook as useAgentRunSchedules
    participant API as GET /agents/{id}/schedules
    participant Svc as AgentRunScheduleService
    participant DB as Postgres
    participant T as Temporal (xN semaphore10)

    UI->>Hook: mount / staleTime expires
    Hook->>API: "?include_live=true&limit=50"
    API->>Svc: "list_schedules(include_live=True)"
    Svc->>DB: list_by_agent_id()
    DB-->>Svc: rows (all)
    Note over Svc: auth filter to visible_rows
    Note over Svc: live_rows = visible_rows[:200]
    par asyncio.gather semaphore 10
        Svc->>T: describe_schedule(id_1)
        T-->>Svc: ScheduleDescription
        Svc->>T: describe_schedule(id_2)
        T-->>Svc: ScheduleDescription or Exception
    end
    Note over Svc: live_data_available True or False per row
    Svc-->>API: AgentRunScheduleListResponse
    API-->>Hook: JSON run_schedules total
    Hook-->>UI: data staleTime 30s
    Note over UI: upcoming filter next_action_times not null
    Note over UI: notice if live_data_available is false
```

</a>
</details>

<sub>Reviews (5): Last reviewed commit: ["Merge branch &#39;main&#39;
into
jerome/schedule..."](4cf2629)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=45786376)</sub>

<!-- /greptile_comment -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

agentex-ui/components/scheduled-tasks/scheduled-tasks-page.tsx

@@ -27,7 +27,6 @@ import {
 import { useAgentByName } from '@/hooks/use-agent-by-name';
 import {
   SCHEDULE_LIST_LIMIT,
-  useAgentRunScheduleDetailsForItems,
   useAgentRunSchedules,
   useAgentRunSchedulesForAgents,
 } from '@/hooks/use-agent-run-schedules';
@@ -90,30 +89,27 @@ export function ScheduledTasksPage() {
 
   const baseItems =
     scheduleScope === ScheduleScope.ALL ? allItems : currentItems;
-  const detailQueries = useAgentRunScheduleDetailsForItems(
-    agentexClient,
-    baseItems
-  );
-  const schedulesWithLiveFields = useMemo(
+  const unavailableLiveDataCount = useMemo(
     () =>
-      baseItems.map((item, index) => ({
-        ...item,
-        schedule: detailQueries[index]?.data ?? item.schedule,
-      })),
-    [baseItems, detailQueries]
+      baseItems.filter(
+        item =>
+          !isSchedulePaused(item.schedule) &&
+          item.schedule.live_data_available === false
+      ).length,
+    [baseItems]
   );
 
   const visibleItems = useMemo(() => {
     const scopedItems =
       scheduleView === 'upcoming'
-        ? schedulesWithLiveFields.filter(
+        ? baseItems.filter(
             item =>
               !isSchedulePaused(item.schedule) &&
               getNextRunTime(item.schedule) != null
           )
-        : schedulesWithLiveFields;
+        : baseItems;
     return sortScheduleItems(scopedItems, scheduleView);
-  }, [scheduleView, schedulesWithLiveFields]);
+  }, [baseItems, scheduleView]);
 
   const isLoading =
     scheduleScope === ScheduleScope.ALL
@@ -181,6 +177,17 @@ export function ScheduledTasksPage() {
               Currently showing up to {SCHEDULE_LIST_LIMIT} schedules per agent.
               Support for additional schedules is coming soon.
             </p>
+            {scheduleView === 'upcoming' && unavailableLiveDataCount > 0 && (
+              <p
+                className="border-border bg-muted/40 text-muted-foreground mx-auto w-full max-w-4xl rounded-lg border px-4 py-3 text-xs"
+                role="status"
+              >
+                Next-run data is temporarily unavailable for{' '}
+                {unavailableLiveDataCount}{' '}
+                {unavailableLiveDataCount === 1 ? 'schedule' : 'schedules'}.
+                Their definitions remain available under Schedules.
+              </p>
+            )}
             <ScheduleList
               agentexClient={agentexClient}
               items={visibleItems}

agentex-ui/hooks/use-agent-run-schedules.test.tsx

@@ -1,10 +1,14 @@
 import type { ReactNode } from 'react';
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { act, renderHook } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 
-import { scheduleKeys, useScheduleAction } from './use-agent-run-schedules';
+import {
+  scheduleKeys,
+  useAgentRunSchedules,
+  useScheduleAction,
+} from './use-agent-run-schedules';
 
 import type AgentexSDK from 'agentex';
 
@@ -16,6 +20,47 @@ function createWrapper(queryClient: QueryClient) {
   };
 }
 
+describe('useAgentRunSchedules', () => {
+  it('requests live fields with the bounded schedule list', async () => {
+    const listSchedules = vi.fn().mockResolvedValue({
+      run_schedules: [
+        {
+          id: 'schedule-1',
+          agent_id: 'agent-1',
+          name: 'daily-summary',
+          initial_input: { content: 'Summarize updates' },
+          initial_input_method: 'event/send',
+          next_action_times: ['2026-07-21T13:00:00Z'],
+          live_data_available: true,
+        },
+      ],
+      total: 1,
+    });
+    const agentexClient = {
+      agents: { schedules: { list: listSchedules } },
+    } as unknown as AgentexSDK;
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    const { result } = renderHook(
+      () => useAgentRunSchedules(agentexClient, 'agent-1'),
+      { wrapper: createWrapper(queryClient) }
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(listSchedules).toHaveBeenCalledWith('agent-1', {
+      limit: 50,
+      include_live: true,
+    });
+    expect(result.current.data?.[0]?.next_action_times).toEqual([
+      '2026-07-21T13:00:00Z',
+    ]);
+    expect(result.current.data?.[0]?.live_data_available).toBe(true);
+  });
+});
+
 describe('useScheduleAction', () => {
   it('removes a deleted schedule detail query instead of refetching it', async () => {
     const deleteSchedule = vi

agentex-ui/hooks/use-agent-run-schedules.ts

@@ -27,6 +27,11 @@ export const scheduleKeys = {
 };
 
 export const SCHEDULE_LIST_LIMIT = 50;
+const SCHEDULE_LIST_QUERY = {
+  limit: SCHEDULE_LIST_LIMIT,
+  include_live: true,
+};
+const SCHEDULE_LIST_STALE_TIME = 30_000;
 
 type ScheduleMutationContext = {
   agentexClient: AgentexSDK;
@@ -40,11 +45,6 @@ type ScheduleActionInput =
       scheduledTime: string;
     };
 
-export type AgentRunScheduleListItem = {
-  agentId: string;
-  schedule: AgentRunSchedule;
-};
-
 function errorMessage(error: unknown) {
   return error instanceof Error ? error.message : 'Please try again.';
 }
@@ -59,12 +59,14 @@ export function useAgentRunSchedules(
       if (!agentId) {
         return [];
       }
-      const response = await agentexClient.agents.schedules.list(agentId, {
-        limit: SCHEDULE_LIST_LIMIT,
-      });
+      const response = await agentexClient.agents.schedules.list(
+        agentId,
+        SCHEDULE_LIST_QUERY
+      );
       return response.run_schedules.map(normalizeAgentRunSchedule);
     },
     enabled: !!agentId,
+    staleTime: SCHEDULE_LIST_STALE_TIME,
   });
 }
 
@@ -77,30 +79,14 @@ export function useAgentRunSchedulesForAgents(
     queries: agents.map(agent => ({
       queryKey: scheduleKeys.byAgentId(agent.id),
       queryFn: async () => {
-        const response = await agentexClient.agents.schedules.list(agent.id, {
-          limit: SCHEDULE_LIST_LIMIT,
-        });
+        const response = await agentexClient.agents.schedules.list(
+          agent.id,
+          SCHEDULE_LIST_QUERY
+        );
         return response.run_schedules.map(normalizeAgentRunSchedule);
       },
       enabled,
-    })),
-  });
-}
-
-export function useAgentRunScheduleDetailsForItems(
-  agentexClient: AgentexSDK,
-  items: AgentRunScheduleListItem[]
-) {
-  return useQueries({
-    queries: items.map(({ agentId, schedule }) => ({
-      queryKey: scheduleKeys.detail(agentId, schedule.id),
-      queryFn: async () =>
-        normalizeAgentRunSchedule(
-          await agentexClient.agents.schedules.retrieve(schedule.id, {
-            agent_id: agentId,
-          })
-        ),
-      staleTime: 30_000,
+      staleTime: SCHEDULE_LIST_STALE_TIME,
     })),
   });
 }

agentex-ui/lib/agent-run-schedules.ts

@@ -23,6 +23,7 @@ export type AgentRunSchedule = {
   updated_at: string | null;
   state: 'ACTIVE' | 'PAUSED';
   next_action_times: string[];
+  live_data_available: boolean | null;
   skipped_action_times: string[];
   last_action_time: string | null;
   num_actions_taken: number;
@@ -69,6 +70,7 @@ type AgentRunScheduleResponse = {
   updated_at?: string | null;
   state?: 'ACTIVE' | 'PAUSED';
   next_action_times?: string[];
+  live_data_available?: boolean | null;
   skipped_action_times?: string[];
   last_action_time?: string | null;
   num_actions_taken?: number;
@@ -100,6 +102,7 @@ export function normalizeAgentRunSchedule(
     updated_at: schedule.updated_at ?? null,
     state: schedule.state ?? 'ACTIVE',
     next_action_times: schedule.next_action_times ?? [],
+    live_data_available: schedule.live_data_available ?? null,
     skipped_action_times: schedule.skipped_action_times ?? [],
     last_action_time: schedule.last_action_time ?? null,
     num_actions_taken: schedule.num_actions_taken ?? 0,

agentex-ui/lib/schedule-utils.test.ts

@@ -131,6 +131,7 @@ describe('scheduleToCadence', () => {
     updated_at: null,
     state: 'ACTIVE',
     next_action_times: [],
+    live_data_available: null,
     skipped_action_times: [],
     last_action_time: null,
     num_actions_taken: 0,
@@ -179,6 +180,7 @@ describe('describeCadence', () => {
     updated_at: null,
     state: 'ACTIVE',
     next_action_times: [],
+    live_data_available: null,
     skipped_action_times: [],
     last_action_time: null,
     num_actions_taken: 0,

agentex/openapi.yaml

@@ -3359,6 +3359,15 @@ paths:
           minimum: 1
           default: 100
           title: Limit
+      - name: include_live
+        in: query
+        required: false
+        schema:
+          type: boolean
+          description: Include live Temporal state and upcoming action times.
+          default: false
+          title: Include Live
+        description: Include live Temporal state and upcoming action times.
       responses:
         '200':
           description: Successful Response
@@ -4492,6 +4501,13 @@ components:
           type: array
           title: Next Action Times
           description: Upcoming scheduled fire times.
+        live_data_available:
+          anyOf:
+          - type: boolean
+          - type: 'null'
+          title: Live Data Available
+          description: Whether requested live Temporal fields were retrieved successfully.
+            Null when live enrichment was not requested.
         skipped_action_times:
           items:
             type: string

agentex/src/api/routes/agent_run_schedules.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Annotated, Any
 
 from fastapi import APIRouter, Query, Request
 
@@ -106,7 +106,11 @@ async def list_run_schedules(
     agent_id: str,
     run_schedules_use_case: DAgentRunSchedulesUseCase,
     authorized_schedule_ids: DAuthorizedResourceIds(AgentexResourceType.schedule),
-    limit: int = Query(default=100, ge=1, le=1000),
+    limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+    include_live: Annotated[
+        bool,
+        Query(description="Include live Temporal state and upcoming action times."),
+    ] = False,
 ) -> AgentRunScheduleListResponse:
     """List an agent's run schedules, filtered to those the caller owns.
 
@@ -117,6 +121,7 @@ async def list_run_schedules(
         agent_id,
         authorized_schedule_ids=authorized_schedule_ids,
         limit=limit,
+        include_live=include_live,
     )
 
 

agentex/src/api/schemas/agent_run_schedules.py

@@ -151,6 +151,13 @@ class AgentRunScheduleResponse(BaseModel):
     next_action_times: list[datetime] = Field(
         default_factory=list, description="Upcoming scheduled fire times."
     )
+    live_data_available: bool | None = Field(
+        None,
+        description=(
+            "Whether requested live Temporal fields were retrieved successfully. "
+            "Null when live enrichment was not requested."
+        ),
+    )
     skipped_action_times: list[datetime] = Field(
         default_factory=list, description="Skipped one-off scheduled fire times."
     )