Skip to content

Commit 4ac97be

Browse files
t3dotggclaude
andauthored
feat(scheduler): run a scheduled task once at a specific date and time (#28104)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 955e2bf commit 4ac97be

21 files changed

Lines changed: 671 additions & 84 deletions

‎apps/mobile/src/features/settings/SettingsScheduledTasksRouteScreen.tsx‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,10 @@ const DAYS = [
109109

110110
function describeSchedule(task: ScheduledTask): string {
111111
if (task.schedule.type === "webhook") return "On webhook";
112+
if (task.schedule.type === "once") {
113+
const runAt = new Date(task.schedule.runAt);
114+
return `Once, ${formatRunAtDate(runAt)} at ${formatRunAtTime(runAt)}`;
115+
}
112116
if (task.schedule.type === "interval") return formatScheduledTaskInterval(task.schedule.everyMs);
113117
const days = task.schedule.weekdays?.length ? repeatLabel(task.schedule.weekdays) : "Every day";
114118
return `${days} at ${formatTime(task.schedule.timeOfDay)}`;
@@ -122,6 +126,14 @@ function formatTime(value: string): string {
122126
return time.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
123127
}
124128

129+
function formatRunAtDate(value: Date): string {
130+
return value.toLocaleDateString([], { month: "short", day: "numeric", year: "numeric" });
131+
}
132+
133+
function formatRunAtTime(value: Date): string {
134+
return value.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
135+
}
136+
125137
function timePickerValue(value: string): Date {
126138
const [hours, minutes] = value.split(":").map(Number);
127139
const time = new Date();
@@ -687,6 +699,7 @@ function TaskForm({
687699
});
688700
const submissionPending = useRef(false);
689701
const [timePickerOpen, setTimePickerOpen] = useState(false);
702+
const [runAtPicker, setRunAtPicker] = useState<"date" | "time" | null>(null);
690703
const taskMissing =
691704
draft.task !== null &&
692705
tasks.data !== null &&
@@ -701,6 +714,9 @@ function TaskForm({
701714
}
702715
};
703716

717+
const offersOnce =
718+
config?.environment.capabilities.oneTimeSchedules === true ||
719+
draft.task?.schedule.type === "once";
704720
const save = async () => {
705721
if (
706722
!readEnvironmentScope(environmentId, AuthOrchestrationOperateScope) ||
@@ -728,6 +744,13 @@ function TaskForm({
728744
);
729745
return;
730746
}
747+
if (draft.schedule.mode === "once" && !offersOnce) {
748+
Dialog.alert(
749+
"Once is not available here",
750+
"This environment runs an older T3 Code. Update it to schedule a one-time task, or pick another schedule.",
751+
);
752+
return;
753+
}
731754
const parsedFilters = parseWebhookFilterDrafts(draft.schedule.filters);
732755
if (draft.schedule.mode === "webhook" && "error" in parsedFilters) {
733756
Dialog.alert("Invalid filter", parsedFilters.error);
@@ -964,19 +987,31 @@ function TaskForm({
964987
variant="card"
965988
options={[
966989
{ value: "fixed_time", label: "At a time" },
990+
// Older servers reject one-time schedules on save.
991+
...(offersOnce || draft.schedule.mode === "once"
992+
? [{ value: "once" as const, label: "Once" }]
993+
: []),
967994
{ value: "interval", label: "Interval" },
968995
{ value: "webhook", label: "On webhook" },
969996
]}
970997
selected={draft.schedule.mode}
971998
onSelect={(mode) => {
972999
setTimePickerOpen(false);
1000+
setRunAtPicker(null);
9731001
setDraft({
9741002
...draft,
9751003
prompt:
9761004
mode === "webhook" && !draft.prompt.trim()
9771005
? DEFAULT_WEBHOOK_PROMPT
9781006
: draft.prompt,
979-
schedule: { ...draft.schedule, mode },
1007+
schedule: {
1008+
...draft.schedule,
1009+
mode,
1010+
runAt:
1011+
mode === "once" && !draft.schedule.runAt
1012+
? new Date(Math.ceil(Date.now() / 3_600_000) * 3_600_000).toISOString()
1013+
: draft.schedule.runAt,
1014+
},
9801015
});
9811016
}}
9821017
/>
@@ -1058,6 +1093,53 @@ function TaskForm({
10581093
}}
10591094
/>
10601095
</>
1096+
) : draft.schedule.mode === "once" ? (
1097+
(["date", "time"] as const).map((field) => {
1098+
const runAt = new Date(draft.schedule.runAt);
1099+
const label = field === "date" ? formatRunAtDate(runAt) : formatRunAtTime(runAt);
1100+
return (
1101+
<View key={field}>
1102+
<Pressable
1103+
accessibilityRole="button"
1104+
accessibilityLabel={`${field === "date" ? "Date" : "Time"}, ${label}`}
1105+
onPress={() => setRunAtPicker((open) => (open === field ? null : field))}
1106+
className="min-h-14 flex-row items-center gap-3 border-t border-border-subtle px-4 py-3 active:opacity-70"
1107+
>
1108+
<Text textRole="body" className="text-foreground">
1109+
{field === "date" ? "Date" : "Time"}
1110+
</Text>
1111+
<Text
1112+
textRole="footnote"
1113+
className="min-w-0 flex-1 text-right text-foreground-muted"
1114+
>
1115+
{label}
1116+
</Text>
1117+
<SymbolView
1118+
name="chevron.right"
1119+
size={14}
1120+
tintColorClassName="accent-chevron"
1121+
type="monochrome"
1122+
/>
1123+
</Pressable>
1124+
{runAtPicker === field ? (
1125+
<DateTimePicker
1126+
value={runAt}
1127+
mode={field}
1128+
display={Platform.OS === "ios" ? "spinner" : "default"}
1129+
onDismiss={() => setRunAtPicker(null)}
1130+
onValueChange={(_, selected) => {
1131+
// Android shows a dialog that closes on pick; iOS stays inline.
1132+
if (Platform.OS === "android") setRunAtPicker(null);
1133+
setDraft({
1134+
...draft,
1135+
schedule: { ...draft.schedule, runAt: selected.toISOString() },
1136+
});
1137+
}}
1138+
/>
1139+
) : null}
1140+
</View>
1141+
);
1142+
})
10611143
) : draft.schedule.mode === "webhook" ? (
10621144
<>
10631145
<WebhookScheduleDetails

‎apps/mobile/src/features/settings/scheduledTaskDraft.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,10 @@ export function scheduledTaskDefaultModel(
5151
}
5252

5353
export type ScheduleDraft = {
54-
readonly mode: "fixed_time" | "interval" | "webhook";
54+
readonly mode: "fixed_time" | "once" | "interval" | "webhook";
5555
readonly timeOfDay: string;
56+
/** ISO time for a one-time run. Empty until the user picks the "Once" mode. */
57+
readonly runAt: string;
5658
readonly weekdays: ReadonlyArray<number>;
5759
readonly intervalMinutes: string;
5860
readonly signature: ScheduledTaskWebhookSignature | null;
@@ -68,6 +70,7 @@ export type ScheduleDraft = {
6870
export const DEFAULT_SCHEDULE: ScheduleDraft = {
6971
mode: "fixed_time",
7072
timeOfDay: "09:00",
73+
runAt: "",
7174
weekdays: [1, 2, 3, 4, 5],
7275
intervalMinutes: "15",
7376
signature: null,
@@ -89,6 +92,8 @@ export function scheduleDraftForTask(task: Pick<ScheduledTask, "schedule">): Sch
8992
? [...new Set(task.schedule.weekdays)].sort((a, b) => a - b)
9093
: [0, 1, 2, 3, 4, 5, 6],
9194
};
95+
case "once":
96+
return { ...DEFAULT_SCHEDULE, mode: "once", runAt: task.schedule.runAt };
9297
case "interval":
9398
return {
9499
...DEFAULT_SCHEDULE,
@@ -166,6 +171,10 @@ export function scheduleFromDraft(draft: ScheduleDraft): ScheduledTaskUpsertSche
166171
: {}),
167172
};
168173
}
174+
if (draft.mode === "once") {
175+
const runAt = new Date(draft.runAt);
176+
return Number.isNaN(runAt.getTime()) ? null : { type: "once", runAt: runAt.toISOString() };
177+
}
169178
if (draft.mode === "interval") {
170179
const minutes = parseIntervalMinutes(draft.intervalMinutes);
171180
const everyMs = Math.round(minutes * 60_000);
@@ -215,6 +224,7 @@ function draftSignature(draft: ScheduledTaskDraft): string {
215224
.map((option) => [option.id, option.value]),
216225
draft.schedule.mode,
217226
draft.schedule.timeOfDay,
227+
draft.schedule.runAt,
218228
[...draft.schedule.weekdays].sort((a, b) => a - b),
219229
draft.schedule.intervalMinutes,
220230
draft.schedule.maxDeliveryAgeMinutes,

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,7 @@ export const make = Effect.gen(function* () {
267267
projectOrganization: true,
268268
ignoredFileListing: true,
269269
triage: true,
270+
oneTimeSchedules: true,
270271
npmReleaseLookup: true,
271272
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
272273
...(serverInstallation === null ? {} : { serverInstallation }),

‎apps/server/src/mcp/toolkits/orchestrator/tools.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ const ScheduleTaskTool = Tool.make("schedule_task", {
165165
failureMode: "return",
166166
dependencies,
167167
})
168-
.annotate(Tool.Title, "Schedule a recurring task")
168+
.annotate(Tool.Title, "Schedule a task")
169169
.annotate(Tool.Destructive, true)
170170
.annotate(Tool.OpenWorld, true);
171171

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"claudeSystemAppendBytes": 5153,
33
"codexAdditionalContextBytes": 6883,
4-
"mcpToolListJsonBytes": 47020
4+
"mcpToolListJsonBytes": 47074
55
}

‎apps/server/src/scheduledTasks/Schedule.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@ describe("scheduled task schedule calculation", () => {
2727
});
2828

2929
it("compares schedules structurally", () => {
30+
expect(
31+
isSameSchedule(
32+
{ type: "once", runAt: "2026-11-01T03:00:00-05:00" },
33+
{ type: "once", runAt: "2026-11-01T08:00:00.000Z" },
34+
),
35+
).toBe(true);
3036
expect(
3137
isSameSchedule({ type: "interval", everyMs: 60_000 }, { type: "interval", everyMs: 60_000 }),
3238
).toBe(true);

‎apps/server/src/scheduledTasks/Schedule.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { MIN_SCHEDULED_TASK_INTERVAL_MS, type ScheduledTaskSchedule } from "@t3tools/contracts";
22
import * as DateTime from "effect/DateTime";
3+
import * as Option from "effect/Option";
34

45
const MINUTE_MS = 60_000;
56

@@ -14,6 +15,13 @@ export function nextScheduledRunAt(
1415
from: DateTime.DateTime,
1516
): DateTime.DateTime | null {
1617
if (schedule.type === "webhook") return null;
18+
if (schedule.type === "once") {
19+
const runAt = DateTime.make(schedule.runAt);
20+
return Option.isSome(runAt) &&
21+
DateTime.toEpochMillis(runAt.value) > DateTime.toEpochMillis(from)
22+
? runAt.value
23+
: null;
24+
}
1725
if (schedule.type === "interval") {
1826
// Intervals advance elapsed time, including across daylight-saving changes.
1927
return DateTime.addDuration(from, Math.max(schedule.everyMs, MIN_SCHEDULED_TASK_INTERVAL_MS));
@@ -48,6 +56,7 @@ export function isSameSchedule(a: ScheduledTaskSchedule, b: ScheduledTaskSchedul
4856
return b.type === "interval" && a.everyMs === b.everyMs;
4957
}
5058
if (a.type === "webhook") return b.type === "webhook";
59+
if (a.type === "once") return b.type === "once" && Date.parse(a.runAt) === Date.parse(b.runAt);
5160
if (b.type !== "fixed_time") return false;
5261
// Compare parsed times so padded-hour edits do not reschedule pending runs.
5362
const aTime = parseTimeOfDay(a.timeOfDay);

0 commit comments

Comments
 (0)