setDraft((current) => ({ ...current, timeZone }))}
+ />
) : (
@@ -1754,6 +1800,7 @@
onCheckedChange={(enabled) => setDraft((current) => ({ ...current, enabled }))}
/>
+
```
## apps/web/src/components/settings/scheduledTasksSettings.logic.test.ts
Status: modified; +29; −0
```diff
@@ -151,6 +151,35 @@
});
});
+describe("timed schedule settings", () => {
+ it("round-trips a fixed time's zone, clears it when blank, and rejects an unknown one", () => {
+ const draft = taskToDraft({
+ ...legacyTask,
+ schedule: { type: "fixed_time", timeOfDay: "09:00", timeZone: "America/Chicago" },
+ });
+ expect(draft.timeZone).toBe("America/Chicago");
+ expect(scheduleFromDraft(draft)).toEqual({
+ type: "fixed_time",
+ timeOfDay: "09:00",
+ timeZone: "America/Chicago",
+ });
+ expect(scheduleFromDraft({ ...draft, timeZone: " " })).toMatchObject({ timeZone: null });
+ expect(scheduleFromDraft({ ...draft, timeZone: "Chicago" })).toBeNull();
+ });
+
+ it("keeps a stored zone this client's time zone data lacks when other fields change", () => {
+ const draft = taskToDraft({
+ ...legacyTask,
+ schedule: { type: "fixed_time", timeOfDay: "09:00", timeZone: "Mars/Olympus_Mons" },
+ });
+ expect(scheduleFromDraft({ ...draft, timeOfDay: "10:00" })).toEqual({
+ type: "fixed_time",
+ timeOfDay: "10:00",
+ });
+ expect(scheduleFromDraft({ ...draft, timeZone: "Mars/Tharsis" })).toBeNull();
+ });
+});
+
describe("webhook scheduled tasks", () => {
const signature = { header: "x-signature", encoding: "base64", prefix: "" } as const;
const webhookTask: ScheduledTask = {
```
## apps/web/src/components/settings/scheduledTasksSettings.logic.ts
Status: modified; +25; −3
```diff
@@ -18,6 +18,7 @@
webhookFilterDraftsChanged,
type WebhookFilterDraft,
} from "@t3tools/client-runtime/scheduled-task-webhook";
+import { timeZoneForSave } from "@t3tools/client-runtime/scheduled-task-schedule";
import {
resolveProjectSettings,
@@ -64,6 +65,10 @@
readonly intervalMinutes: string;
readonly timeOfDay: string;
readonly weekdays: ReadonlySet;
+ /** Blank runs at the environment's local time. */
+ readonly timeZone: string;
+ /** The zone the form opened with. */
+ readonly savedTimeZone: string;
readonly projectId: string;
readonly threadId: string;
readonly workspaceMode: WorkspaceMode;
@@ -99,8 +104,22 @@
signaturePrefix: "sha256=",
} as const;
-export function webhookDraftErrors(draft: DraftState) {
- if (draft.scheduleMode !== "webhook") return [];
+export function scheduleDraftErrors(draft: DraftState) {
+ if (draft.scheduleMode === "webhook") return webhookDraftErrors(draft);
+ if (
+ draft.scheduleMode === "fixed" &&
+ timeZoneForSave(draft.timeZone, draft.savedTimeZone) === undefined
+ )
+ return [
+ {
+ title: "Unknown time zone",
+ description: "Pick a time zone such as America/Chicago, or leave it blank.",
+ },
+ ];
+ return [];
+}
+
+function webhookDraftErrors(draft: DraftState) {
if (parseMaxDeliveryAge(draft.maxDeliveryAgeMinutes) === undefined)
return [
{
@@ -147,8 +166,8 @@
}
export function scheduleFromDraft(draft: DraftState): ScheduledTaskUpsertSchedule | null {
+ if (scheduleDraftErrors(draft).length > 0) return null;
if (draft.scheduleMode === "webhook") {
- if (webhookDraftErrors(draft).length > 0) return null;
const maxDeliveryAgeMinutes = parseMaxDeliveryAge(draft.maxDeliveryAgeMinutes);
const replayKey = draft.replayKey.trim();
const coalesceKey = draft.coalesceKey.trim();
@@ -194,6 +213,7 @@
type: "fixed_time",
timeOfDay: draft.timeOfDay || "09:00",
...(selectedEveryDay ? {} : { weekdays: [...draft.weekdays].toSorted() }),
+ ...timeZoneForSave(draft.timeZone, draft.savedTimeZone),
};
}
@@ -215,6 +235,8 @@
schedule.type === "interval" ? String(Math.max(1, schedule.everyMs / 60_000)) : "15",
timeOfDay: schedule.type === "fixed_time" ? schedule.timeOfDay : "09:00",
weekdays,
+ timeZone: schedule.type === "fixed_time" ? (schedule.timeZone ?? "") : "",
+ savedTimeZone: schedule.type === "fixed_time" ? (schedule.timeZone ?? "") : "",
projectId: task.projectId,
threadId: task.threadId ?? "",
workspaceMode: task.workspaceStrategy.type,
```
## docs/user/project-settings.md
Status: modified; +10; −1
```diff
@@ -66,7 +66,8 @@
ones across your connected environments. Use the settings filter to narrow the
list by environment or project. Each task runs on the environment you choose,
using its project, model, and workspace settings. Fixed-time schedules use that
+environment's time zone, which may differ from your phone's, unless the task
+sets its own.
-environment's time zone, which may differ from your phone's.
Deleting a thread also deletes tasks that post into that thread. Tasks that start
a new thread on each run survive deletion of their previous threads.
@@ -76,6 +77,14 @@
immediately.
Leaving an edited form asks before discarding unsaved changes.
+## Scheduled task timing
+
+A task that runs **At a time** uses the environment's clock unless you set a
+**Time zone**, such as `America/Chicago`. It then keeps that local time when
+daylight saving starts or ends. A time skipped when clocks move forward runs
+later by the size of the change, and a time that repeats when they move back
+runs once.
+
## Webhook automations
In **Settings → Scheduled tasks**, choose **On webhook**
```
## packages/client-runtime/package.json
Status: modified; +4; −0
```diff
@@ -59,6 +59,10 @@
"types": "./src/scheduledTaskWebhook.ts",
"default": "./src/scheduledTaskWebhook.ts"
},
+ "./scheduled-task-schedule": {
+ "types": "./src/scheduledTaskSchedule.ts",
+ "default": "./src/scheduledTaskSchedule.ts"
+ },
"./connection": {
"types": "./src/connection/index.ts",
"default": "./src/connection/index.ts"
```
## packages/client-runtime/src/scheduledTaskSchedule.ts
Status: added; +37; −0
```diff
@@ -1,0 +1,37 @@
+import { isValidTimeZone } from "@t3tools/contracts";
+
+/** Blank means the environment's local time; undefined means the text is not a zone this client knows. */
+function parseTimeZoneDraft(value: string): string | null | undefined {
+ const zone = value.trim();
+ if (zone === "") return null;
+ // Intl matches names case-insensitively; store the canonical spelling.
+ return isValidTimeZone(zone)
+ ? Intl.DateTimeFormat("en-US", { timeZone: zone }).resolvedOptions().timeZone
+ : undefined;
+}
+
+/**
+ * The `timeZone` part of a fixed-time save, or undefined when the entry blocks saving.
+ * A zone left as it was loaded is omitted when this client's time zone data lacks it;
+ * the server keeps the stored zone, so other edits to the task still save.
+ */
+export function timeZoneForSave(
+ value: string,
+ saved: string,
+): { readonly timeZone?: string | null } | undefined {
+ const timeZone = parseTimeZoneDraft(value);
+ if (timeZone !== undefined) return { timeZone };
+ return value === saved ? {} : undefined;
+}
+
+export function localTimeZone(): string {
+ return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+/** Zones this client knows, starting with its own. */
+export function timeZoneSuggestions(): ReadonlyArray {
+ const local = localTimeZone();
+ const known =
+ typeof Intl.supportedValuesOf === "function" ? Intl.supportedValuesOf("timeZone") : [];
+ return [local, ...known.filter((zone) => zone !== local)];
+}
```
## packages/contracts/src/orchestratorMcp.ts
Status: modified; +1; −1
```diff
@@ -67,7 +67,7 @@
OrchestratorMcpScheduleFromJsonString,
]).annotate({
description:
- "Trigger object: {type:'interval', everyMs}, {type:'fixed_time', timeOfDay, weekdays?}, or {type:'webhook'} to run on each request to a generated URL. Never stringify it unless the provider requires the compatibility form.",
+ "Trigger object: {type:'interval', everyMs}, {type:'fixed_time', timeOfDay, weekdays?, timeZone?}, or {type:'webhook'} to run on each request to a generated URL. Never stringify it unless the provider requires the compatibility form.",
});
const OrchestratorMcpTargetOptionsFromRecord = Schema.Record(
```
## packages/contracts/src/scheduledTask.test.ts
Status: modified; +17; −0
```diff
@@ -22,6 +22,23 @@
everyMs: MIN_SCHEDULED_TASK_INTERVAL_MS - 1,
});
});
+
+ it("checks a written time zone against Intl but reads any stored one", () => {
+ const fixed = { type: "fixed_time", timeOfDay: "09:00" };
+ expect(decodeUpsertSchedule({ ...fixed, timeZone: "America/Chicago" })).toEqual({
+ ...fixed,
+ timeZone: "America/Chicago",
+ });
+ expect(decodeUpsertSchedule({ ...fixed, timeZone: null })).toEqual({
+ ...fixed,
+ timeZone: null,
+ });
+ expect(() => decodeUpsertSchedule({ ...fixed, timeZone: "Mars/Olympus_Mons" })).toThrow();
+ expect(decodeSchedule({ ...fixed, timeZone: "Mars/Olympus_Mons" })).toEqual({
+ ...fixed,
+ timeZone: "Mars/Olympus_Mons",
+ });
+ });
});
it.each(["literal", " ", "\t\n", "{{body.bad", "{{unknown.field}}"])(
```
## packages/contracts/src/scheduledTask.ts
Status: modified; +39; −3
```diff
@@ -1,3 +1,5 @@
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import {
@@ -23,6 +25,23 @@
Schema.isPattern(/^([01]?\d|2[0-3]):([0-5]\d)$/),
).annotate({ description: "Local wall-clock time in 24-hour HH:MM form, such as 09:30." });
+/** Whether this runtime's Intl data knows the time zone. */
+export function isValidTimeZone(value: string): boolean {
+ return Option.isSome(DateTime.zoneMakeNamed(value));
+}
+
+/**
+ * Stored zones are read without the Intl check, so a client whose time zone
+ * data lacks one still lists the task.
+ */
+const ScheduledTaskTimeZone = TrimmedNonEmptyString.annotate({
+ description: "IANA time zone name, such as America/Chicago.",
+});
+
+const WritableTimeZone = ScheduledTaskTimeZone.check(
+ Schema.makeFilter((value) => isValidTimeZone(value) || `Unknown time zone: ${value}`),
+);
+
export const MIN_SCHEDULED_TASK_INTERVAL_MS = 60_000;
const ScheduledTaskIntervalMs = Schema.Int.check(Schema.isGreaterThan(0)).annotate({
@@ -38,7 +57,7 @@
description: "Run repeatedly after a fixed number of milliseconds.",
});
-const ScheduledTaskFixedTimeSchedule = Schema.Struct({
+const ScheduledTaskFixedTimeFields = {
type: Schema.Literal("fixed_time").annotate({
description: "Select a fixed local wall-clock time.",
}),
@@ -52,8 +71,25 @@
description: "Optional weekdays; omit to run every day.",
}),
),
+};
+
+const ScheduledTaskFixedTimeSchedule = Schema.Struct({
+ ...ScheduledTaskFixedTimeFields,
+ timeZone: Schema.optional(ScheduledTaskTimeZone),
}).annotate({
+ description:
+ "Run at a fixed wall-clock time on selected weekdays, in timeZone or the environment's local time.",
+});
+
+const ScheduledTaskUpsertFixedTimeSchedule = Schema.Struct({
+ ...ScheduledTaskFixedTimeFields,
+ timeZone: Schema.optional(Schema.NullOr(WritableTimeZone)).annotate({
+ description:
+ "IANA time zone for timeOfDay, such as America/Chicago. Without one, the time is the environment's local time. Omit to keep the stored zone; null removes it.",
- description: "Run at a fixed local wall-clock time on selected weekdays.",
+ }),
+}).annotate({
+ description:
+ "Run at a fixed wall-clock time on selected weekdays, in timeZone or the environment's local time.",
});
const ScheduledTaskWebhookSignatureFields = {
@@ -214,7 +250,7 @@
}).annotate({
description: "Run repeatedly after a fixed number of milliseconds.",
}),
- ScheduledTaskFixedTimeSchedule,
+ ScheduledTaskUpsertFixedTimeSchedule,
ScheduledTaskUpsertWebhookSchedule,
]).annotate({
description: "Writable trigger. Pass an object with type 'interval', 'fixed_time' or 'webhook'.",
```
## packages/provider-core/src/server/orchestrationInstructions.ts
Status: modified; +1; −1
```diff
@@ -13,7 +13,7 @@
- A delegated task/subagent is child work owned by the current thread. Use \`orchestrator_capabilities\` to discover the current provider/model IDs from the same live catalog as the composer, including configured custom models. It lists a short set of models per provider; pass \`search\` to find others. Do not treat a native tool's model list as the full list of available subagent models. Prefer native subagent tools for same-provider work only when they support the chosen model and no model options are requested or inherited. Use \`delegate_task\` with that provider instance and model when native tools cannot, including for same-provider work. Also use \`delegate_task\` for cross-provider or explicitly T3-owned child tasks. For a child task that needs a separate checkout, use \`delegate_task\` with \`isolation:"worktree"\` across any provider or model. It starts from the parent local commit and runs project setup; uncommitted edits are not copied. Retain each returned \`taskId\`, and use \`task_status\` or \`task_cancel\` to manage it. The returned \`childThreadId\` is backing storage for the subagent, not the target for starting another delegated review round.
- \`t3_thread_launch\` and \`create_threads\` create ordinary top-level T3 conversations. Use them only when the user explicitly asks for separate/new/top-level threads or conversations. Never use them merely because the user said "subagent" or requested parallel delegated work.
- For every T3 delegated review round, call \`delegate_task\` again. Include the original brief, prior findings, responses, and unresolved objections in each new task prompt. Track each round by its own \`taskId\`. Use a distinct \`clientRequestId\` per round, stable across retries of that round. Do not use \`t3_thread_send\` on \`childThreadId\` to continue a delegated review.`,
- `- \`schedule_task\` creates persistent recurring work in the app scheduler. Pass \`schedule\` as a structured object, never as JSON text: \`{"type":"interval","everyMs":3600000}\` for an interval, or \`{"type":"fixed_time","timeOfDay":"09:00","weekdays":[1,2,3,4,5]}\` for a wall-clock schedule, or \`{"type":"webhook"}\` to run on each request to the returned \`webhookUrl\` (the run sees the request only through \`{{body.path}}\`-style placeholders in the prompt). By default runs return to the current thread, which suits orchestrating: each trigger arrives here and you delegate or dedupe; set \`bindToCurrentThread=false\` only when the user wants a fresh thread for every run. After scheduling a timer, report the returned cadence and next run time; for a webhook, report its \`webhookUrl\`, or say T3 Connect remote access is needed if it is missing.
+ `- \`schedule_task\` creates persistent recurring work in the app scheduler. Pass \`schedule\` as a structured object, never as JSON text: \`{"type":"interval","everyMs":3600000}\` for an interval, or \`{"type":"fixed_time","timeOfDay":"09:00","weekdays":[1,2,3,4,5]}\` for a wall-clock schedule (add \`"timeZone":"America/Chicago"\` when the user's clock differs from the environment's), or \`{"type":"webhook"}\` to run on each request to the returned \`webhookUrl\` (the run sees the request only through \`{{body.path}}\`-style placeholders in the prompt). By default runs return to the current thread, which suits orchestrating: each trigger arrives here and you delegate or dedupe; set \`bindToCurrentThread=false\` only when the user wants a fresh thread for every run. After scheduling a timer, report the returned cadence and next run time; for a webhook, report its \`webhookUrl\`, or say T3 Connect remote access is needed if it is missing.
- When you need a secret from the user (a token, API key, or webhook signing secret), call \`request_secret\` so they enter it privately, then pass the returned \`secretRef\` to the tool that needs it, e.g. \`signature.secretRef\` on a webhook task for a sender that signs requests such as GitHub. A \`secretRef\` works once. Never ask for a secret in chat, never invent one, and never repeat one.
- To mention another thread to the user, link it as \`[title](t3-thread://v1/)\` with its exact \`threadId\`, not URL-encoded. T3 Code opens the thread in the app and shows its current title.`,
`### Choose the workspace before starting a new thread
```