feat(webapp): add default and minimum schedule spread windows

Mono-RevId: 6be9d1ef1f2ed06bbd9a6511417cc33c33eb189e

Author: carderne

.changeset/free-schedule-applied-policy.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Add an optional `appliedSchedulePolicy` field to the schedule API response. It is present only when a non-overridable plan policy applies a minimum window to a schedule (e.g. a free-plan schedule's minimum run interval); the configured `window` continues to be returned separately and unchanged.

.server-changes/schedule-default-window.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+New schedules use a default CRON spread window when none is set, distributing runs after their scheduled time instead of starting them all at once. Set an explicit window to override the default.

.server-changes/schedule-minimum-window.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Schedules now support a configurable minimum spread window that applies even when a smaller window is requested.

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

@@ -56,6 +56,7 @@ type ScheduleInspectorData = {
   cronDescription: string;
   timezone: string;
   window?: string;
+  windowSource?: "explicit" | "schedule_default";
   externalId: string | null;
   deduplicationKey: string | null;
   userProvidedDeduplicationKey: boolean;
@@ -145,7 +146,10 @@ export function ScheduleInspector({
               </Property.Item>
               <Property.Item>
                 <Property.Label>Window</Property.Label>
-                <Property.Value>{schedule.window ?? "-"}</Property.Value>
+                <Property.Value>
+                  {schedule.window ?? "-"}
+                  {schedule.windowSource === "schedule_default" ? " · Default" : ""}
+                </Property.Value>
               </Property.Item>
               <Property.Item className="gap-1">
                 <Property.Label>Environment</Property.Label>

apps/webapp/app/env.server.ts

@@ -1837,7 +1837,7 @@ const EnvironmentSchema = z
     SCHEDULE_WORKER_CRON_SPREAD_FRACTION: z.coerce
       .number()
       .catch(0)
-      .default(0)
+      .default(1)
       .transform((value) => (Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0)),
 
     SCHEDULE_WORKER_REDIS_HOST: z

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

@@ -127,6 +127,8 @@ export class EditSchedulePresenter {
         timezone: true,
         windowDurationSeconds: true,
         windowPercentage: true,
+        defaultWindowDurationSeconds: true,
+        minimumWindowDurationSeconds: true,
         taskIdentifier: true,
         instances: {
           select: {
@@ -147,7 +149,12 @@ export class EditSchedulePresenter {
     return {
       ...schedule,
       cron: schedule.generatorExpression,
+      // The form shows only the user-configured value; a blank field lets a captured default
+      // surface through the placeholder copy rather than appearing as a typed value.
       window: formatScheduleWindow(schedule),
+      // Whether this schedule carries a captured default, so the form copy can say "clearing
+      // returns to the 60-minute default" only for the new cohort, never for a grandfathered row.
+      hasCapturedDefaultWindow: schedule.defaultWindowDurationSeconds !== null,
       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,7 +5,8 @@ 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 { formatResolvedScheduleWindow } from "~/v3/scheduleWindow.server";
+import { type ScheduleWindowSource } from "@internal/schedule-engine";
 import { CheckScheduleService } from "~/v3/services/checkSchedule.server";
 import { resolveScheduleTimings } from "~/v3/scheduleTimings.server";
 import { env } from "~/env.server";
@@ -37,6 +38,8 @@ type ScheduleListItem = {
   cronDescription: string;
   timezone: string;
   window?: string;
+  windowSource?: ScheduleWindowSource;
+  minimumWindowDurationSeconds: number | null;
   externalId: string | null;
   nextRun: Date;
   nextRunEffectiveAt: Date;
@@ -223,6 +226,8 @@ export class ScheduleListPresenter extends BasePresenter {
         timezone: true,
         windowDurationSeconds: true,
         windowPercentage: true,
+        defaultWindowDurationSeconds: true,
+        minimumWindowDurationSeconds: true,
         externalId: true,
         instances: {
           select: {
@@ -300,6 +305,8 @@ export class ScheduleListPresenter extends BasePresenter {
         schedulePhase: instances[index].schedulePhase,
         windowDurationSeconds: schedule.windowDurationSeconds,
         windowPercentage: schedule.windowPercentage,
+        defaultWindowDurationSeconds: schedule.defaultWindowDurationSeconds,
+        minimumWindowDurationSeconds: schedule.minimumWindowDurationSeconds,
         active: schedule.active,
         updatedAt: schedule.updatedAt,
       })),
@@ -308,6 +315,7 @@ export class ScheduleListPresenter extends BasePresenter {
 
     const schedules: ScheduleListItem[] = rawSchedules.map((schedule, index) => {
       const { nextRun, nextRunEffectiveAt, lastRun } = timings[index];
+      const resolvedWindow = formatResolvedScheduleWindow(schedule);
 
       return {
         id: schedule.id,
@@ -319,7 +327,9 @@ export class ScheduleListPresenter extends BasePresenter {
         cron: schedule.generatorExpression,
         cronDescription: schedule.generatorDescription,
         timezone: schedule.timezone,
-        window: formatScheduleWindow(schedule),
+        window: resolvedWindow.window,
+        windowSource: resolvedWindow.source,
+        minimumWindowDurationSeconds: schedule.minimumWindowDurationSeconds,
         active: schedule.active,
         externalId: schedule.externalId,
         lastRun,

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

@@ -5,7 +5,10 @@ import { displayableEnvironment } from "~/models/runtimeEnvironment.server";
 import { clickhouseFactory } from "~/services/clickhouse/clickhouseFactoryInstance.server";
 import { NextRunListPresenter } from "./NextRunListPresenter.server";
 import { scheduleWhereClause } from "~/models/schedules.server";
-import { calculateNextScheduleRunTimes, formatScheduleWindow } from "~/v3/scheduleWindow.server";
+import {
+  calculateNextScheduleRunTimes,
+  formatResolvedScheduleWindow,
+} from "~/v3/scheduleWindow.server";
 import { env } from "~/env.server";
 
 type ViewScheduleOptions = {
@@ -40,6 +43,8 @@ export class ViewSchedulePresenter {
         timezone: true,
         windowDurationSeconds: true,
         windowPercentage: true,
+        defaultWindowDurationSeconds: true,
+        minimumWindowDurationSeconds: true,
         externalId: true,
         deduplicationKey: true,
         userProvidedDeduplicationKey: true,
@@ -101,6 +106,8 @@ export class ViewSchedulePresenter {
           phaseSecret: env.ENCRYPTION_KEY,
           windowDurationSeconds: schedule.windowDurationSeconds,
           windowPercentage: schedule.windowPercentage,
+          defaultWindowDurationSeconds: schedule.defaultWindowDurationSeconds,
+          minimumWindowDurationSeconds: schedule.minimumWindowDurationSeconds,
           count: 5,
         })
       : [];
@@ -120,7 +127,8 @@ export class ViewSchedulePresenter {
         timezone: schedule.timezone,
         cron: schedule.generatorExpression,
         cronDescription: schedule.generatorDescription,
-        window: formatScheduleWindow(schedule),
+        window: formatResolvedScheduleWindow(schedule).window,
+        windowSource: formatResolvedScheduleWindow(schedule).source,
         nextRuns,
         runs,
         environments: schedule.instances.map((instance) => {
@@ -168,6 +176,13 @@ export class ViewSchedulePresenter {
       active: result.schedule.active,
       nextRun: result.schedule.nextRuns[0]?.nominalAt ?? null,
       nextRunEffectiveAt: result.schedule.nextRuns[0]?.effectiveAt ?? null,
+      appliedSchedulePolicy:
+        result.schedule.minimumWindowDurationSeconds !== null
+          ? {
+              minimumWindowSeconds: result.schedule.minimumWindowDurationSeconds,
+              reason: "free_schedule" as const,
+            }
+          : undefined,
       generator: {
         type: "CRON",
         expression: result.schedule.cron,

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

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

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

@@ -73,6 +73,7 @@ export async function action({ request }: ActionFunctionArgs) {
       environments: schedule.environments,
       nextRun: schedule.nextRun,
       nextRunEffectiveAt: schedule.nextRunEffectiveAt,
+      appliedSchedulePolicy: schedule.appliedSchedulePolicy,
     };
 
     return json(responseObject, { status: 200 });
@@ -133,6 +134,13 @@ export async function loader({ request }: LoaderFunctionArgs) {
       active: schedule.active,
       nextRun: schedule.nextRun,
       nextRunEffectiveAt: schedule.nextRunEffectiveAt,
+      appliedSchedulePolicy:
+        schedule.minimumWindowDurationSeconds !== null
+          ? {
+              minimumWindowSeconds: schedule.minimumWindowDurationSeconds,
+              reason: "free_schedule" as const,
+            }
+          : undefined,
       environments: schedule.environments,
     })),
     pagination: {