feat: surface cron windows in webapp, cli, sdk

Author: carderne

.changeset/smooth-schedule-windows.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+"trigger.dev": patch
+---
+
+Define stable execution windows on declarative scheduled tasks. Schedule API responses now expose both the nominal CRON time and its assigned time, while deploy output and the dashboard show configured windows and upcoming assignments.

apps/webapp/app/components/schedules/ScheduleInspector.tsx

@@ -55,13 +55,14 @@ export type ScheduleInspectorData = {
   cron: string;
   cronDescription: string;
   timezone: string;
+  window?: string;
   externalId: string | null;
   deduplicationKey: string | null;
   userProvidedDeduplicationKey: boolean;
   active: boolean;
   environments: EnvironmentRow[];
   runs: RunRow[];
-  nextRuns: Date[];
+  nextRuns: Array<{ nominalAt: Date; effectiveAt: Date }>;
 };
 
 type Props = {
@@ -142,6 +143,10 @@ export function ScheduleInspector({
                 <Property.Label>Timezone</Property.Label>
                 <Property.Value>{schedule.timezone}</Property.Value>
               </Property.Item>
+              <Property.Item>
+                <Property.Label>Window</Property.Label>
+                <Property.Value>{schedule.window ?? "Default (60 seconds)"}</Property.Value>
+              </Property.Item>
               <Property.Item className="gap-1">
                 <Property.Label>Environment</Property.Label>
                 <Property.Value>
@@ -195,12 +200,13 @@ export function ScheduleInspector({
             />
           </div>
           <div className="flex flex-col gap-1 pt-2">
-            <Header3 className="pb-1 pl-3">Next 5 runs</Header3>
+            <Header3 className="pb-1 pl-3">Next 5 scheduled runs</Header3>
             <Table variant="bright">
               <TableHeader>
                 <TableRow>
-                  {!isUtc && <TableHeaderCell>{schedule.timezone}</TableHeaderCell>}
-                  <TableHeaderCell>UTC</TableHeaderCell>
+                  {!isUtc && <TableHeaderCell>CRON ({schedule.timezone})</TableHeaderCell>}
+                  <TableHeaderCell>CRON (UTC)</TableHeaderCell>
+                  <TableHeaderCell>Assigned (UTC)</TableHeaderCell>
                 </TableRow>
               </TableHeader>
               <TableBody>
@@ -210,21 +216,24 @@ export function ScheduleInspector({
                       <TableRow key={index}>
                         {!isUtc && (
                           <TableCell>
-                            <DateTime date={run} timeZone={schedule.timezone} />
+                            <DateTime date={run.nominalAt} timeZone={schedule.timezone} />
                           </TableCell>
                         )}
                         <TableCell>
-                          <DateTime date={run} timeZone="UTC" />
+                          <DateTime date={run.nominalAt} timeZone="UTC" />
+                        </TableCell>
+                        <TableCell>
+                          <DateTime date={run.effectiveAt} timeZone="UTC" />
                         </TableCell>
                       </TableRow>
                     ))
                   ) : (
-                    <TableBlankRow colSpan={isUtc ? 1 : 2}>
+                    <TableBlankRow colSpan={isUtc ? 2 : 3}>
                       <PlaceholderText title="You found a bug" />
                     </TableBlankRow>
                   )
                 ) : (
-                  <TableBlankRow colSpan={isUtc ? 1 : 2}>
+                  <TableBlankRow colSpan={isUtc ? 2 : 3}>
                     <PlaceholderText title="Schedule disabled" />
                   </TableBlankRow>
                 )}
@@ -249,8 +258,8 @@ export function ScheduleInspector({
                 }
                 panelClassName="max-w-full"
               >
-                You can only edit a declarative schedule by updating your schedules.task and then
-                running the CLI dev and deploy commands.
+                You can only edit a declarative schedule, including its window, by updating your
+                schedules.task and then running the CLI dev and deploy commands.
               </InfoPanel>
             </div>
           )}

apps/webapp/app/presenters/v3/EditSchedulePresenter.server.ts

@@ -6,6 +6,7 @@ import { filterOrphanedEnvironments } from "~/utils/environmentSort";
 import { getTimezones } from "~/utils/timezones.server";
 import { findCurrentWorkerFromEnvironment } from "~/v3/models/workerDeployment.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
+import { formatScheduleWindow } from "~/v3/scheduleWindow.server";
 
 type EditScheduleOptions = {
   userId: string;
@@ -124,6 +125,8 @@ export class EditSchedulePresenter {
         deduplicationKey: true,
         userProvidedDeduplicationKey: true,
         timezone: true,
+        windowDurationSeconds: true,
+        windowPercentage: true,
         taskIdentifier: true,
         instances: {
           select: {
@@ -144,6 +147,7 @@ export class EditSchedulePresenter {
     return {
       ...schedule,
       cron: schedule.generatorExpression,
+      window: formatScheduleWindow(schedule),
       environments: schedule.instances.flatMap((instance) => {
         const environment = possibleEnvironments.find((env) => env.id === instance.environmentId);
         if (!environment) {

apps/webapp/app/presenters/v3/ScheduleListPresenter.server.ts

@@ -5,12 +5,10 @@ import { getTaskIdentifiers } from "~/models/task.server";
 import { getCurrentPlan, getPlans } from "~/services/platform.v3.server";
 import { findCurrentWorkerFromEnvironment } from "~/v3/models/workerDeployment.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
-import { formatScheduleWindow } from "~/v3/scheduleWindow.server";
+import { calculateNextScheduleRunTimes, formatScheduleWindow } from "~/v3/scheduleWindow.server";
 import { CheckScheduleService } from "~/v3/services/checkSchedule.server";
-import {
-  calculateNextScheduledTimestampFromNow,
-  previousScheduledTimestamp,
-} from "~/v3/utils/calculateNextSchedule.server";
+import { previousScheduledTimestamp } from "~/v3/utils/calculateNextSchedule.server";
+import { env } from "~/env.server";
 import { BasePresenter } from "./basePresenter.server";
 
 type ScheduleListOptions = {
@@ -35,6 +33,7 @@ export type ScheduleListItem = {
   window?: string;
   externalId: string | null;
   nextRun: Date;
+  nextRunEffectiveAt: Date;
   lastRun: Date | undefined;
   active: boolean;
   environments: {
@@ -223,6 +222,7 @@ export class ScheduleListPresenter extends BasePresenter {
         instances: {
           select: {
             environmentId: true,
+            schedulePhase: true,
           },
         },
         active: true,
@@ -300,6 +300,23 @@ export class ScheduleListPresenter extends BasePresenter {
         }
       }
 
+      const instance = schedule.instances.find(
+        (instance) => instance.environmentId === environmentId
+      );
+      if (!instance) {
+        throw new Error(`Schedule instance not found for environment: ${environmentId}`);
+      }
+      const [nextRun] = calculateNextScheduleRunTimes({
+        cron: schedule.generatorExpression,
+        timezone: schedule.timezone,
+        deduplicationKey: schedule.deduplicationKey,
+        environmentId,
+        schedulePhase: instance.schedulePhase,
+        phaseSecret: env.ENCRYPTION_KEY,
+        windowDurationSeconds: schedule.windowDurationSeconds,
+        windowPercentage: schedule.windowPercentage,
+      });
+
       return {
         id: schedule.id,
         type: schedule.type,
@@ -314,10 +331,8 @@ export class ScheduleListPresenter extends BasePresenter {
         active: schedule.active,
         externalId: schedule.externalId,
         lastRun,
-        nextRun: calculateNextScheduledTimestampFromNow(
-          schedule.generatorExpression,
-          schedule.timezone
-        ),
+        nextRun: nextRun.nominalAt,
+        nextRunEffectiveAt: nextRun.effectiveAt,
         environments: schedule.instances.map((instance) => {
           const environment = project.environments.find((env) => env.id === instance.environmentId);
           if (!environment) {

apps/webapp/app/presenters/v3/ViewSchedulePresenter.server.ts

@@ -3,10 +3,10 @@ import type { PrismaClient } from "~/db.server";
 import { prisma } from "~/db.server";
 import { displayableEnvironment } from "~/models/runtimeEnvironment.server";
 import { clickhouseFactory } from "~/services/clickhouse/clickhouseFactoryInstance.server";
-import { nextScheduledTimestamps } from "~/v3/utils/calculateNextSchedule.server";
 import { NextRunListPresenter } from "./NextRunListPresenter.server";
 import { scheduleWhereClause } from "~/models/schedules.server";
-import { formatScheduleWindow } from "~/v3/scheduleWindow.server";
+import { calculateNextScheduleRunTimes, formatScheduleWindow } from "~/v3/scheduleWindow.server";
+import { env } from "~/env.server";
 
 type ViewScheduleOptions = {
   userId?: string;
@@ -52,6 +52,8 @@ export class ViewSchedulePresenter {
         },
         instances: {
           select: {
+            environmentId: true,
+            schedulePhase: true,
             environment: {
               select: {
                 id: true,
@@ -82,8 +84,25 @@ export class ViewSchedulePresenter {
       return;
     }
 
+    const instance = schedule.instances.find(
+      (instance) => instance.environmentId === environmentId
+    );
+    if (!instance) {
+      return;
+    }
+
     const nextRuns = schedule.active
-      ? nextScheduledTimestamps(schedule.generatorExpression, schedule.timezone, new Date(), 5)
+      ? calculateNextScheduleRunTimes({
+          cron: schedule.generatorExpression,
+          timezone: schedule.timezone,
+          deduplicationKey: schedule.deduplicationKey,
+          environmentId,
+          schedulePhase: instance.schedulePhase,
+          phaseSecret: env.ENCRYPTION_KEY,
+          windowDurationSeconds: schedule.windowDurationSeconds,
+          windowPercentage: schedule.windowPercentage,
+          count: 5,
+        })
       : [];
 
     const runs = includeRunHistory
@@ -101,6 +120,7 @@ export class ViewSchedulePresenter {
         timezone: schedule.timezone,
         cron: schedule.generatorExpression,
         cronDescription: schedule.generatorDescription,
+        window: formatScheduleWindow(schedule),
         nextRuns,
         runs,
         environments: schedule.instances.map((instance) => {
@@ -146,14 +166,15 @@ export class ViewSchedulePresenter {
       type: result.schedule.type,
       task: result.schedule.taskIdentifier,
       active: result.schedule.active,
-      nextRun: result.schedule.nextRuns[0],
+      nextRun: result.schedule.nextRuns[0]?.nominalAt ?? null,
+      nextRunEffectiveAt: result.schedule.nextRuns[0]?.effectiveAt ?? null,
       generator: {
         type: "CRON",
         expression: result.schedule.cron,
         description: result.schedule.cronDescription,
       },
       timezone: result.schedule.timezone,
-      window: formatScheduleWindow(result.schedule),
+      window: result.schedule.window,
       externalId: result.schedule.externalId ?? undefined,
       deduplicationKey: result.schedule.userProvidedDeduplicationKey
         ? (result.schedule.deduplicationKey ?? undefined)

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

@@ -972,8 +972,10 @@ type ScheduleRow = {
   type: "DECLARATIVE" | "IMPERATIVE";
   cron: string;
   cronDescription: string;
+  window?: string;
   externalId: string | null;
   nextRun: Date;
+  nextRunEffectiveAt: Date;
   lastRun: Date | undefined;
   active: boolean;
 };
@@ -993,7 +995,7 @@ function SchedulesMiniTable({
     return (
       <Table variant={variant} showTopBorder={showTopBorder}>
         <TableBody>
-          <TableBlankRow colSpan={6}>
+          <TableBlankRow colSpan={9}>
             <Paragraph variant="small" className="flex items-center justify-center">
               No schedules attached to this task yet.
             </Paragraph>
@@ -1009,9 +1011,11 @@ function SchedulesMiniTable({
         <TableRow>
           <TableHeaderCell>Schedule ID</TableHeaderCell>
           <TableHeaderCell>Type</TableHeaderCell>
-          <TableHeaderCell>Cron</TableHeaderCell>
+          <TableHeaderCell>CRON</TableHeaderCell>
+          <TableHeaderCell>Window</TableHeaderCell>
           <TableHeaderCell>External ID</TableHeaderCell>
-          <TableHeaderCell>Next run</TableHeaderCell>
+          <TableHeaderCell>Next CRON time</TableHeaderCell>
+          <TableHeaderCell>Next assigned time</TableHeaderCell>
           <TableHeaderCell>Last run</TableHeaderCell>
           <TableHeaderCell>Status</TableHeaderCell>
         </TableRow>
@@ -1036,6 +1040,9 @@ function SchedulesMiniTable({
               <TableCell onClick={open}>
                 <span className="font-mono text-xs">{schedule.cron}</span>
               </TableCell>
+              <TableCell onClick={open}>
+                <span className="text-xs">{schedule.window ?? "Default (60s)"}</span>
+              </TableCell>
               <TableCell onClick={open}>
                 {schedule.externalId ? (
                   <span className="font-mono text-xs">{schedule.externalId}</span>
@@ -1046,6 +1053,9 @@ function SchedulesMiniTable({
               <TableCell onClick={open}>
                 <RelativeDateTime date={schedule.nextRun} />
               </TableCell>
+              <TableCell onClick={open}>
+                <RelativeDateTime date={schedule.nextRunEffectiveAt} />
+              </TableCell>
               <TableCell onClick={open}>
                 {schedule.lastRun ? (
                   <RelativeDateTime date={schedule.lastRun} />

apps/webapp/app/routes/api.v1.deployments.$deploymentId.ts

@@ -1,9 +1,11 @@
 import { type LoaderFunctionArgs, json } from "@remix-run/server-runtime";
-import { type GetDeploymentResponseBody } from "@trigger.dev/core/v3";
+import { BackgroundWorkerMetadata, type GetDeploymentResponseBody } from "@trigger.dev/core/v3";
 import { z } from "zod";
 import { prisma } from "~/db.server";
 import { authenticateApiKeyWithScope } from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
+import { env } from "~/env.server";
+import { calculateNextScheduleRunTimes, normalizeScheduleWindow } from "~/v3/scheduleWindow.server";
 
 const ParamsSchema = z.object({
   deploymentId: z.string(),
@@ -53,6 +55,43 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
       return json({ error: "Deployment not found" }, { status: 404 });
     }
 
+    const workerMetadata = deployment.worker
+      ? BackgroundWorkerMetadata.safeParse(deployment.worker.metadata)
+      : undefined;
+    const declarativeSchedules = workerMetadata?.success
+      ? workerMetadata.data.tasks.flatMap((task) => {
+          if (
+            !task.schedule ||
+            (task.schedule.environments &&
+              !task.schedule.environments.includes(authenticatedEnv.type))
+          ) {
+            return [];
+          }
+
+          const windowFields = normalizeScheduleWindow(task.schedule.window);
+          const [nextRun] = calculateNextScheduleRunTimes({
+            cron: task.schedule.cron,
+            timezone: task.schedule.timezone,
+            deduplicationKey: task.id,
+            environmentId: authenticatedEnv.id,
+            schedulePhase: null,
+            phaseSecret: env.ENCRYPTION_KEY,
+            ...windowFields,
+          });
+
+          return [
+            {
+              task: task.id,
+              cron: task.schedule.cron,
+              timezone: task.schedule.timezone,
+              window: task.schedule.window,
+              nextRun: nextRun.nominalAt,
+              nextRunEffectiveAt: nextRun.effectiveAt,
+            },
+          ];
+        })
+      : [];
+
     return json({
       id: deployment.friendlyId,
       status: deployment.status,
@@ -75,6 +114,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
               filePath: task.filePath,
               exportName: task.exportName ?? "@deprecated",
             })),
+            declarativeSchedules,
           }
         : undefined,
       integrationDeployments:

apps/webapp/app/routes/api.v1.schedules.$scheduleId.ts

@@ -130,6 +130,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
           deduplicationKey: schedule.deduplicationKey,
           environments: schedule.environments,
           nextRun: schedule.nextRun,
+          nextRunEffectiveAt: schedule.nextRunEffectiveAt,
         };
 
         return json(responseObject, { status: 200 });