loopengine 0.1.93 → 0.1.95

package/README.md

@@ -253,7 +253,12 @@ The server runs one scheduler (`core/scheduler.ts`) that sends a message
 to an agent later — once (`run_at`) or on an interval (`every: "1h"`),
 optionally from a set first run (`start_at`), which every later run keeps:
 `every: "1d"` from a 9:00 start runs daily at 9:00, `every: "7d"` from a
-Monday runs on Mondays — from the console's **Schedules** tab, the `GET/POST
+Monday runs on Mondays. `at: "09:00"` (plus `weekday: "monday"`) picks
+that start for you. Times of day are in the workspace's time zone, chosen
+in the console's **Settings** (`LOOPENGINE_TIME_ZONE`; the server's own
+when unset): a timestamp without an offset is read there, and daily and
+weekly tasks keep their time of day when the clocks change. Schedule
+from the console's **Schedules** tab, the `GET/POST
 /agents/<name>/schedules` API, or the agent itself: every agent has
 built-in `system_schedule_task`, `system_list_scheduled_tasks`,
 `system_check_scheduled_task` and `system_cancel_scheduled_task` tools,

package/dist/core/scheduler.d.ts

@@ -1,8 +1,12 @@
+/** `time_zone` (repeating in whole days only): the zone whose calendar
+ * days it steps through, so its time of day survives daylight saving.
+ * Tasks made before it existed step in exact 24-hour days. */
 export type Schedule = {
     run_at: string;
 } | {
     every: string;
     anchor?: string;
+    time_zone?: string;
 };
 export type ScheduledTaskStatus = 'scheduled' | 'running' | 'awaiting_approval' | 'paused' | 'done' | 'cancelled';
 export interface ScheduledTaskRun {
@@ -77,11 +81,16 @@ export interface CreateScheduledTaskInput {
      * time of day / day of week every later run keeps, e.g. every "1d"
      * from "2026-11-02T09:00:00+08:00" runs daily at 9:00. A start in the
      * past is fine: the first run is its next slot after now. Without it,
-     * the first run is one interval from now. */
+     * the first run is one interval from now. `at` ("09:00", with `every`
+     * only) instead starts it at the next 9:00 in the workspace's time
+     * zone, and `weekday` ("monday", or 0 for Sunday to 6) at the next one
+     * on that day. */
     schedule: {
         run_at?: unknown;
         every?: unknown;
         start_at?: unknown;
+        at?: unknown;
+        weekday?: unknown;
     };
     task_name?: string;
     notify?: boolean;
@@ -101,6 +110,13 @@ export declare function resumeScheduledTask(taskId: string, nowMs?: number): Pro
  * finished one-off task runs once more. */
 export declare function runScheduledTaskNow(taskId: string, nowMs?: number): Promise<ScheduledTask>;
 export declare function deleteScheduledTask(taskId: string): Promise<void>;
+/** Moves every daily and weekly (whole-day) task to `toTimeZone`,
+ * keeping its time of day: a 9:00 task made while the workspace was on
+ * UTC runs at 9:00 in the new zone. A task from before tasks kept their
+ * zone is taken to be in `fromTimeZone`. One-off and shorter repeating
+ * tasks are left alone: they're a moment, not a time of day. Returns
+ * how many moved. */
+export declare function moveScheduledTasksToTimeZone(fromTimeZone: string, toTimeZone: string, nowMs?: number): Promise<number>;
 /** When the next task is due — for a host that stops idle servers and
  * needs to wake this one in time (GET /internal/activity). */
 export declare function nextScheduledWakeAt(): Promise<string | undefined>;

package/dist/core/scheduler.js

@@ -12,15 +12,19 @@
 // `every` is anchored: an hourly task created at 10:07 keeps firing at
 // :07, however long each run takes. `start_at` sets the anchor instead,
 // for "daily at 9:00" ("1d" from a 9:00 start) or "Mondays at 9:00" ("7d"
-// from a Monday). Intervals are exact durations, so in a time zone with
-// daylight saving a daily 9:00 task runs at 8:00 or 10:00 local time
-// after the clocks change. A run missed while the server was down fires
+// from a Monday), or `at` ("09:00", plus a `weekday` for "7d") works the
+// start out in the workspace's time zone (core/time-zone.ts). Intervals
+// in days are calendar days in the time zone the task was made in, so a
+// daily 9:00 task stays at 9:00 when the clocks change; shorter ones are
+// exact durations. Timestamps without an offset are read in the
+// workspace's time zone too. A run missed while the server was down fires
 // once when it's back, then the schedule moves to the next future slot
 // (no burst of catch-up runs).
 import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { KeyedMutex } from './session-store.js';
+import { addCalendarDays, instantOf, nextTimeOfDay, parseTimeOfDay, parseTimestamp, wallTimeAt, workspaceTimeZone } from './time-zone.js';
 const HISTORY_LIMIT = 20;
 const EVERY_PATTERN = /^(\d+)\s*(s|m|h|d)$/;
 const EVERY_UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
@@ -37,11 +41,38 @@ export function parseEvery(every) {
         throw new ScheduleError(`"${every}" is too short — the shortest interval is 30s`);
     return ms;
 }
-/** The first anchored slot strictly after `nowMs`. */
-function nextAnchoredSlot(anchorMs, intervalMs, nowMs) {
+/** Whole days in an interval ("2d" → 2), or undefined for one in s/m/h. */
+function everyDays(every) {
+    const match = EVERY_PATTERN.exec(every.trim());
+    return match && match[2] === 'd' ? Number(match[1]) : undefined;
+}
+/** The first anchored slot strictly after `nowMs`: exact steps of
+ * `intervalMs`, or with `days` and `timeZone`, steps of that many
+ * calendar days there. */
+function nextAnchoredSlot(anchorMs, intervalMs, nowMs, calendar) {
     if (nowMs < anchorMs)
         return anchorMs;
-    return anchorMs + (Math.floor((nowMs - anchorMs) / intervalMs) + 1) * intervalMs;
+    let k = Math.floor((nowMs - anchorMs) / intervalMs) + 1;
+    if (!calendar)
+        return anchorMs + k * intervalMs;
+    // A day is 23 to 25 hours, so the estimate can be one step off.
+    const slot = (n) => addCalendarDays(anchorMs, n * calendar.days, calendar.timeZone);
+    while (k > 1 && slot(k - 1) > nowMs)
+        k--;
+    while (slot(k) <= nowMs)
+        k++;
+    return slot(k);
+}
+const WEEKDAY_NAMES = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+function parseWeekday(value) {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 6)
+        return value;
+    if (typeof value === 'string') {
+        const i = WEEKDAY_NAMES.findIndex((d) => d.startsWith(value.trim().toLowerCase()) && value.trim().length >= 3);
+        if (i >= 0)
+            return i;
+    }
+    throw new ScheduleError(`weekday "${String(value)}" isn't a day: use monday to sunday, or 0 (Sunday) to 6`);
 }
 /** Human-readable schedule, for lists and messages. */
 export function describeSchedule(schedule) {
@@ -114,34 +145,53 @@ export async function createScheduledTask(input, nowMs = Date.now()) {
         throw new ScheduleError('message is required');
     let schedule;
     let nextRunMs;
+    const timeZone = workspaceTimeZone();
     if (typeof input.schedule?.run_at === 'string' && input.schedule.run_at) {
-        const runAtMs = Date.parse(input.schedule.run_at);
+        const runAtMs = parseTimestamp(input.schedule.run_at, timeZone);
         if (Number.isNaN(runAtMs))
             throw new ScheduleError(`"${input.schedule.run_at}" is not a valid ISO 8601 timestamp`);
         schedule = { run_at: new Date(runAtMs).toISOString() };
         nextRunMs = runAtMs;
     }
     else if (typeof input.schedule?.every === 'string' && input.schedule.every) {
-        const intervalMs = parseEvery(input.schedule.every);
-        const startAt = input.schedule.start_at;
-        if (startAt !== undefined && startAt !== null && startAt !== '') {
-            const startMs = typeof startAt === 'string' ? Date.parse(startAt) : Number.NaN;
+        const every = input.schedule.every.trim();
+        const intervalMs = parseEvery(every);
+        const days = everyDays(every);
+        const calendar = days ? { days, timeZone } : undefined;
+        const { start_at: startAt, at, weekday } = input.schedule;
+        const given = (v) => v !== undefined && v !== null && v !== '';
+        let startMs;
+        if (given(at)) {
+            if (given(startAt))
+                throw new ScheduleError('give either start_at or at, not both');
+            const time = typeof at === 'string' ? parseTimeOfDay(at) : undefined;
+            if (!time)
+                throw new ScheduleError(`at "${String(at)}" isn't a time of day: use 24-hour "HH:MM", e.g. "09:00"`);
+            startMs = nextTimeOfDay(time, nowMs, timeZone, given(weekday) ? parseWeekday(weekday) : undefined);
+        }
+        else if (given(weekday)) {
+            throw new ScheduleError('weekday goes with at, e.g. { "every": "7d", "at": "09:00", "weekday": "monday" }');
+        }
+        else if (given(startAt)) {
+            startMs = typeof startAt === 'string' ? parseTimestamp(startAt, timeZone) : Number.NaN;
             if (Number.isNaN(startMs))
                 throw new ScheduleError(`start_at "${String(startAt)}" is not a valid ISO 8601 timestamp`);
+        }
+        if (startMs !== undefined) {
             // The anchor is the start itself, so every run lands on its time of
             // day (or weekday, for "7d").
-            nextRunMs = nextAnchoredSlot(startMs, intervalMs, nowMs);
-            schedule = { every: input.schedule.every.trim(), anchor: new Date(startMs).toISOString() };
+            nextRunMs = nextAnchoredSlot(startMs, intervalMs, nowMs, calendar);
+            schedule = { every, anchor: new Date(startMs).toISOString(), ...(calendar ? { time_zone: timeZone } : {}) };
         }
         else {
-            nextRunMs = nowMs + intervalMs;
-            schedule = { every: input.schedule.every.trim(), anchor: new Date(nextRunMs).toISOString() };
+            nextRunMs = calendar ? addCalendarDays(nowMs, calendar.days, timeZone) : nowMs + intervalMs;
+            schedule = { every, anchor: new Date(nextRunMs).toISOString(), ...(calendar ? { time_zone: timeZone } : {}) };
         }
     }
     else {
-        if (input.schedule?.start_at)
-            throw new ScheduleError('start_at goes with "every" (a repeating task); a one-off task uses run_at');
-        throw new ScheduleError('schedule must be { "run_at": "<ISO timestamp>" } or { "every": "<interval, e.g. 1h>", "start_at"?: "<ISO timestamp>" }');
+        if (input.schedule?.start_at || input.schedule?.at)
+            throw new ScheduleError('start_at and at go with "every" (a repeating task); a one-off task uses run_at');
+        throw new ScheduleError('schedule must be { "run_at": "<ISO timestamp>" } or { "every": "<interval, e.g. 1h>", "start_at"?: "<ISO timestamp>" } or { "every": "1d", "at": "09:00" }');
     }
     const task = {
         task_id: randomUUID(),
@@ -197,6 +247,36 @@ export async function runScheduledTaskNow(taskId, nowMs = Date.now()) {
 export async function deleteScheduledTask(taskId) {
     await getSchedulerStore().remove(taskId);
 }
+/** Moves every daily and weekly (whole-day) task to `toTimeZone`,
+ * keeping its time of day: a 9:00 task made while the workspace was on
+ * UTC runs at 9:00 in the new zone. A task from before tasks kept their
+ * zone is taken to be in `fromTimeZone`. One-off and shorter repeating
+ * tasks are left alone: they're a moment, not a time of day. Returns
+ * how many moved. */
+export async function moveScheduledTasksToTimeZone(fromTimeZone, toTimeZone, nowMs = Date.now()) {
+    let moved = 0;
+    for (const listed of await getSchedulerStore().list()) {
+        if (listed.status === 'done' || listed.status === 'cancelled' || !('every' in listed.schedule) || !everyDays(listed.schedule.every))
+            continue;
+        await getSchedulerStore().update(listed.task_id, (t) => {
+            if (!t || !('every' in t.schedule) || !t.schedule.anchor)
+                return t;
+            const days = everyDays(t.schedule.every);
+            const from = t.schedule.time_zone ?? fromTimeZone;
+            if (!days || from === toTimeZone)
+                return t;
+            const anchorMs = instantOf(wallTimeAt(Date.parse(t.schedule.anchor), from), toTimeZone);
+            const schedule = { ...t.schedule, anchor: new Date(anchorMs).toISOString(), time_zone: toTimeZone };
+            moved++;
+            // A run that's due or under way keeps its slot; the next one moves.
+            if (t.status !== 'scheduled' || !t.next_run_at || Date.parse(t.next_run_at) <= nowMs)
+                return { ...t, schedule };
+            const next = nextAnchoredSlot(anchorMs, parseEvery(t.schedule.every), nowMs, { days, timeZone: toTimeZone });
+            return { ...t, schedule, next_run_at: new Date(next).toISOString() };
+        });
+    }
+    return moved;
+}
 /** When the next task is due — for a host that stops idle servers and
  * needs to wake this one in time (GET /internal/activity). */
 export async function nextScheduledWakeAt() {
@@ -208,7 +288,8 @@ function nextRunAfter(task, nowMs) {
         return undefined;
     const intervalMs = parseEvery(task.schedule.every);
     const anchorMs = task.schedule.anchor ? Date.parse(task.schedule.anchor) : Date.parse(task.created_at) + intervalMs;
-    return nextAnchoredSlot(anchorMs, intervalMs, nowMs);
+    const days = everyDays(task.schedule.every);
+    return nextAnchoredSlot(anchorMs, intervalMs, nowMs, days && task.schedule.time_zone ? { days, timeZone: task.schedule.time_zone } : undefined);
 }
 /** Moves the old lp-task-scheduler's task files (`<dir>/.tasks/*.json`)
  * into this store once, renaming each to `.json.migrated`. Returns how

package/dist/core/system-agents/templates.d.ts

@@ -13,7 +13,7 @@ export interface TemplateSkill {
 export interface TemplateSchedule {
     /** How often, in the scheduler's terms: "10m", "1h", "7d". */
     every: string;
-    /** Optional first run, as a time of day in the server's time zone
+    /** Optional first run, as a time of day in the workspace's time zone
      * ("09:00"), and for weekly schedules a weekday (1 = Monday). Without
      * it, the first run is one interval after the schedule is turned on. */
     at?: string;
@@ -49,5 +49,5 @@ export interface StarterTemplate {
 export declare const STARTER_TEMPLATES: readonly StarterTemplate[];
 export declare function starterTemplate(id: string): StarterTemplate | undefined;
 /** The first run of a template's schedule: its time of day (and weekday)
- * next, in the server's time zone; undefined when it has none. */
-export declare function templateScheduleStart(schedule: TemplateSchedule, nowMs?: number): string | undefined;
+ * next, in the workspace's time zone; undefined when it has none. */
+export declare function templateScheduleStart(schedule: TemplateSchedule, nowMs?: number, timeZone?: string): string | undefined;

package/dist/core/system-agents/templates.js

@@ -1,3 +1,4 @@
+import { nextTimeOfDay, parseTimeOfDay, workspaceTimeZone } from '../time-zone.js';
 const GMAIL_KEYS = ['GMAIL_CLIENT_ID', 'GMAIL_CLIENT_SECRET', 'GMAIL_REFRESH_TOKEN'];
 const SHOPIFY_KEYS = ['SHOPIFY_STORE_DOMAIN', 'SHOPIFY_ADMIN_TOKEN'];
 const GITHUB_KEYS = ['GITHUB_TOKEN', 'GITHUB_DEFAULT_REPO'];
@@ -378,19 +379,10 @@ export function starterTemplate(id) {
     return STARTER_TEMPLATES.find((t) => t.id === id);
 }
 /** The first run of a template's schedule: its time of day (and weekday)
- * next, in the server's time zone; undefined when it has none. */
-export function templateScheduleStart(schedule, nowMs = Date.now()) {
-    if (!schedule.at)
+ * next, in the workspace's time zone; undefined when it has none. */
+export function templateScheduleStart(schedule, nowMs = Date.now(), timeZone = workspaceTimeZone()) {
+    const at = schedule.at ? parseTimeOfDay(schedule.at) : undefined;
+    if (!at)
         return undefined;
-    const [hours, minutes] = schedule.at.split(':').map(Number);
-    const start = new Date(nowMs);
-    start.setHours(hours, minutes, 0, 0);
-    if (schedule.weekday !== undefined) {
-        const ahead = (schedule.weekday - start.getDay() + 7) % 7;
-        start.setDate(start.getDate() + ahead);
-    }
-    const step = schedule.weekday !== undefined ? 7 : 1;
-    while (start.getTime() <= nowMs)
-        start.setDate(start.getDate() + step);
-    return start.toISOString();
+    return new Date(nextTimeOfDay(at, nowMs, timeZone, schedule.weekday)).toISOString();
 }

package/dist/core/system-tools/schedule.js

@@ -1,4 +1,5 @@
 import { cancelScheduledTask, createScheduledTask, getScheduledTask, listScheduledTasks, } from '../scheduler.js';
+import { formatWallTime, workspaceTimeZone } from '../time-zone.js';
 /** How many active (not done or cancelled) tasks one agent may create
  * through these tools — each run is a model call, so a runaway loop of
  * "schedule another one" stops here. The console and API aren't capped. */
@@ -6,7 +7,12 @@ function maxActivePerAgent() {
     const n = Number(process.env.LOOPENGINE_SCHEDULER_MAX_PER_AGENT);
     return Number.isInteger(n) && n > 0 ? n : 25;
 }
-function summary(t) {
+/** next_run_at as the workspace's wall-clock time, so the model can
+ * confirm "tomorrow at 9:00" without converting from UTC. */
+function nextRunLocal(t, timeZone) {
+    return t.next_run_at ? `${formatWallTime(Date.parse(t.next_run_at), timeZone)} (${timeZone})` : undefined;
+}
+function summary(t, timeZone) {
     return {
         task_id: t.task_id,
         task_name: t.task_name,
@@ -14,11 +20,15 @@ function summary(t) {
         schedule: t.schedule,
         status: t.status,
         next_run_at: t.next_run_at,
+        next_run_local: nextRunLocal(t, timeZone),
         run_count: t.run_count,
         last_status: t.last_status,
     };
 }
 export function createScheduleTools(agentName) {
+    // Read once per run: the time zone is in the tool description, which
+    // should stay the same from call to call.
+    const timeZone = workspaceTimeZone();
     async function ownTask(taskId, tool) {
         const task = await getScheduledTask(taskId);
         // Another agent's task reads exactly like a missing one.
@@ -28,7 +38,7 @@ export function createScheduleTools(agentName) {
     }
     const scheduleTask = {
         name: 'system_schedule_task',
-        description: 'Schedule a message to yourself for later — once at a set time, or repeatedly on an interval — like setting a reminder or a cron job. When it fires you receive the message as a new conversation (none of the current one carries over, so make the message self-contained) and handle it with your tools as usual, with no person live. A tool call that needs approval goes wherever your approval requests are sent and waits; if nowhere is set, it is denied. Use only when the user asks for something to happen later or regularly, never on your own initiative. Use the user\'s time zone (ask if unclear), prefer the longest interval that serves them since each run is a model call, and confirm the schedule back in plain words. Returns task_id and next_run_at.',
+        description: 'Schedule a message to yourself for later — once at a set time, or repeatedly on an interval — like setting a reminder or a cron job. When it fires you receive the message as a new conversation (none of the current one carries over, so make the message self-contained) and handle it with your tools as usual, with no person live. A tool call that needs approval goes wherever your approval requests are sent and waits; if nowhere is set, it is denied. Use only when the user asks for something to happen later or regularly, never on your own initiative. Times are in this workspace\'s time zone, ' + timeZone + ', unless you give an offset, so when the user means another time zone, give its offset. Prefer the longest interval that serves them since each run is a model call, and confirm the schedule back in plain words. Returns task_id, next_run_at and next_run_local (the workspace\'s time).',
         input_schema: {
             type: 'object',
             properties: {
@@ -38,8 +48,8 @@ export function createScheduleTools(agentName) {
                 },
                 schedule: {
                     type: 'object',
-                    description: 'Either { "run_at": "<ISO 8601 timestamp with time zone>" } for once, or { "every": "<interval>", "start_at"?: "<ISO 8601 timestamp with time zone>" } to repeat until cancelled — a number plus s/m/h/d, e.g. "30m", "1h", "1d"; 30s at the shortest. A repeating task keeps its first slot: started at 10:07 with "1h", it fires at 11:07, 12:07, ... Use start_at to pick that first slot, for a time of day or day of week: "every day at 9am" is every "1d" with start_at the next 9:00 in the user\'s time zone; "every Monday at 9am" is every "7d" with start_at the next Monday 9:00.',
-                    properties: { run_at: { type: 'string' }, every: { type: 'string' }, start_at: { type: 'string' } },
+                    description: 'Either { "run_at": "<ISO 8601 timestamp>" } for once, or { "every": "<interval>", ... } to repeat until cancelled — a number plus s/m/h/d, e.g. "30m", "1h", "1d"; 30s at the shortest. A timestamp without an offset, like "2026-11-02T09:00", is in the workspace\'s time zone (' + timeZone + '). A repeating task keeps its first slot: started at 10:07 with "1h", it fires at 11:07, 12:07, ... For a time of day or day of week, add "at" (24-hour "HH:MM") and for weekly "weekday": "every day at 9am" is { "every": "1d", "at": "09:00" }; "every Monday at 9am" is { "every": "7d", "at": "09:00", "weekday": "monday" }. Daily and weekly tasks keep their time of day when the clocks change. Or give "start_at", a timestamp, for the first run.',
+                    properties: { run_at: { type: 'string' }, every: { type: 'string' }, at: { type: 'string' }, weekday: { type: 'string' }, start_at: { type: 'string' } },
                 },
                 task_name: { type: 'string', description: 'Optional short label, shown when listing tasks and in the console.' },
                 notify: { type: 'boolean', description: 'Optional — also send each run\'s result through your notifier (where your approval requests go), so a person sees it.' },
@@ -58,7 +68,7 @@ export function createScheduleTools(agentName) {
                 task_name: typeof input.task_name === 'string' ? input.task_name : undefined,
                 notify: input.notify === true,
             });
-            return JSON.stringify({ task_id: task.task_id, next_run_at: task.next_run_at, schedule: task.schedule });
+            return JSON.stringify({ task_id: task.task_id, next_run_at: task.next_run_at, next_run_local: nextRunLocal(task, timeZone), schedule: task.schedule });
         },
     };
     const listTasks = {
@@ -76,7 +86,7 @@ export function createScheduleTools(agentName) {
         },
         execute: async (input) => {
             const status = typeof input.status === 'string' ? input.status : undefined;
-            return JSON.stringify((await listScheduledTasks({ agent: agentName, status })).map(summary));
+            return JSON.stringify((await listScheduledTasks({ agent: agentName, status })).map((t) => summary(t, timeZone)));
         },
         safe: true,
     };

package/dist/core/time-zone.d.ts

@@ -0,0 +1,40 @@
+export declare const TIME_ZONE_ENV = "LOOPENGINE_TIME_ZONE";
+export interface WallTime {
+    year: number;
+    /** 1–12 */
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+export declare function isValidTimeZone(timeZone: unknown): timeZone is string;
+/** The server's own time zone. */
+export declare function serverTimeZone(): string;
+/** The workspace's time zone: LOOPENGINE_TIME_ZONE when it's a real one,
+ * else the server's. */
+export declare function workspaceTimeZone(): string;
+/** Every time zone this server knows, for the console's picker. */
+export declare function listTimeZones(): string[];
+/** The wall-clock time (and weekday, 0 = Sunday) at `ms` in `timeZone`. */
+export declare function wallTimeAt(ms: number, timeZone: string): WallTime & {
+    weekday: number;
+};
+/** The instant a wall-clock time in `timeZone` happens. Fields may
+ * overflow (day 32, hour 25), as with Date.UTC. */
+export declare function instantOf(t: WallTime, timeZone: string): number;
+/** An ISO 8601 timestamp as ms. One with a "Z" or an offset is exact;
+ * one without ("2026-11-02T09:00") is a wall-clock time in `timeZone`.
+ * NaN when it isn't a timestamp. */
+export declare function parseTimestamp(value: string, timeZone: string): number;
+/** "09:00" as [hours, minutes], or undefined when it isn't a time. */
+export declare function parseTimeOfDay(value: string): [number, number] | undefined;
+/** The next time it's `at` ("09:00") in `timeZone`, strictly after
+ * `nowMs`, on `weekday` (0 = Sunday) when given. */
+export declare function nextTimeOfDay(at: [number, number], nowMs: number, timeZone: string, weekday?: number): number;
+/** `ms` moved by whole calendar days in `timeZone`, keeping its time of
+ * day across a daylight-saving change. */
+export declare function addCalendarDays(ms: number, days: number, timeZone: string): number;
+/** `ms` as "2026-11-02 09:00" in `timeZone`, for tool results the model
+ * reads back to a person. */
+export declare function formatWallTime(ms: number, timeZone: string): string;

package/dist/core/time-zone.js

@@ -0,0 +1,138 @@
+// The workspace's time zone: what "9:00" means in a schedule, a
+// template's start time and the console's date fields. Set from the
+// console's Settings (LOOPENGINE_TIME_ZONE, an IANA name such as
+// "America/New_York"); unset, it's the server's own, which on a hosted
+// workspace is UTC.
+//
+// Times are worked out with Intl alone, no time zone data of our own:
+// a wall-clock time is turned into an instant by guessing its offset
+// and correcting it twice, which settles on the right answer either side
+// of a daylight-saving change. A time the clocks skip (02:30 on the
+// morning they spring forward) lands an hour later; a time that happens
+// twice (the hour they fall back) is the first of the two.
+export const TIME_ZONE_ENV = 'LOOPENGINE_TIME_ZONE';
+const formatters = new Map();
+function formatter(timeZone) {
+    let f = formatters.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+            weekday: 'short',
+        });
+        formatters.set(timeZone, f);
+    }
+    return f;
+}
+export function isValidTimeZone(timeZone) {
+    if (typeof timeZone !== 'string' || !timeZone.trim())
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The server's own time zone. */
+export function serverTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+/** The workspace's time zone: LOOPENGINE_TIME_ZONE when it's a real one,
+ * else the server's. */
+export function workspaceTimeZone() {
+    const configured = process.env[TIME_ZONE_ENV]?.trim();
+    return configured && isValidTimeZone(configured) ? configured : serverTimeZone();
+}
+/** Every time zone this server knows, for the console's picker. */
+export function listTimeZones() {
+    const supported = Intl.supportedValuesOf?.('timeZone') ?? [];
+    return supported.includes('UTC') ? supported : ['UTC', ...supported];
+}
+const WEEKDAY_INDEX = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+/** The wall-clock time (and weekday, 0 = Sunday) at `ms` in `timeZone`. */
+export function wallTimeAt(ms, timeZone) {
+    const parts = {};
+    for (const p of formatter(timeZone).formatToParts(new Date(ms)))
+        parts[p.type] = p.value;
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour),
+        minute: Number(parts.minute),
+        second: Number(parts.second),
+        weekday: WEEKDAY_INDEX[parts.weekday] ?? 0,
+    };
+}
+function asUtcMs(t) {
+    return Date.UTC(t.year, t.month - 1, t.day, t.hour, t.minute, t.second);
+}
+/** How far ahead of UTC `timeZone` is at `ms`, in ms. */
+function offsetAt(ms, timeZone) {
+    return asUtcMs(wallTimeAt(Math.floor(ms / 1000) * 1000, timeZone)) - Math.floor(ms / 1000) * 1000;
+}
+/** The instant a wall-clock time in `timeZone` happens. Fields may
+ * overflow (day 32, hour 25), as with Date.UTC. */
+export function instantOf(t, timeZone) {
+    const naive = asUtcMs(t);
+    const first = naive - offsetAt(naive, timeZone);
+    const second = naive - offsetAt(first, timeZone);
+    // Either side of a change the two guesses differ; the earlier one is
+    // right for a repeated hour, the later one for a skipped hour.
+    if (first === second)
+        return first;
+    return offsetAt(Math.min(first, second), timeZone) === naive - Math.min(first, second) ? Math.min(first, second) : Math.max(first, second);
+}
+const LOCAL_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?$/;
+/** An ISO 8601 timestamp as ms. One with a "Z" or an offset is exact;
+ * one without ("2026-11-02T09:00") is a wall-clock time in `timeZone`.
+ * NaN when it isn't a timestamp. */
+export function parseTimestamp(value, timeZone) {
+    const local = LOCAL_TIMESTAMP.exec(value.trim());
+    if (!local)
+        return Date.parse(value);
+    const [, y, mo, d, h, mi, s] = local;
+    const t = { year: Number(y), month: Number(mo), day: Number(d), hour: Number(h), minute: Number(mi), second: Number(s ?? 0) };
+    if (t.month < 1 || t.month > 12 || t.day < 1 || t.day > 31 || t.hour > 23 || t.minute > 59 || t.second > 59)
+        return Number.NaN;
+    return instantOf(t, timeZone);
+}
+const TIME_OF_DAY = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+/** "09:00" as [hours, minutes], or undefined when it isn't a time. */
+export function parseTimeOfDay(value) {
+    const match = TIME_OF_DAY.exec(value.trim());
+    return match ? [Number(match[1]), Number(match[2])] : undefined;
+}
+/** The next time it's `at` ("09:00") in `timeZone`, strictly after
+ * `nowMs`, on `weekday` (0 = Sunday) when given. */
+export function nextTimeOfDay(at, nowMs, timeZone, weekday) {
+    const today = wallTimeAt(nowMs, timeZone);
+    const ahead = weekday === undefined ? 0 : (weekday - today.weekday + 7) % 7;
+    const step = weekday === undefined ? 1 : 7;
+    for (let days = ahead;; days += step) {
+        const ms = instantOf({ year: today.year, month: today.month, day: today.day + days, hour: at[0], minute: at[1], second: 0 }, timeZone);
+        if (ms > nowMs)
+            return ms;
+    }
+}
+/** `ms` moved by whole calendar days in `timeZone`, keeping its time of
+ * day across a daylight-saving change. */
+export function addCalendarDays(ms, days, timeZone) {
+    const t = wallTimeAt(ms, timeZone);
+    return instantOf({ ...t, day: t.day + days }, timeZone);
+}
+/** `ms` as "2026-11-02 09:00" in `timeZone`, for tool results the model
+ * reads back to a person. */
+export function formatWallTime(ms, timeZone) {
+    const t = wallTimeAt(ms, timeZone);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${t.year}-${pad(t.month)}-${pad(t.day)} ${pad(t.hour)}:${pad(t.minute)}`;
+}

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { setUsageSink, recordUsage, type UsageEvent, type UsageSink } from '#cor
 export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS, type NotifierFile, type MessagingApprover } from '#core/notifier-file.js';
 export { listDeliveries, recordDelivery, type NotifierDelivery } from '#core/notifier-deliveries.js';
 export { describeNotifier } from '#core/http-notifier.js';
-export { Scheduler, ScheduleError, FileSchedulerStore, getSchedulerStore, setSchedulerStore, createScheduledTask, listScheduledTasks, getScheduledTask, cancelScheduledTask, pauseScheduledTask, resumeScheduledTask, runScheduledTaskNow, deleteScheduledTask, nextScheduledWakeAt, importLegacyScheduledTasks, parseEvery, describeSchedule, type ScheduledTask, type ScheduledTaskRun, type ScheduledTaskStatus, type Schedule, type SchedulerStore, type FireTask, type CreateScheduledTaskInput } from '#core/scheduler.js';
+export { Scheduler, ScheduleError, FileSchedulerStore, getSchedulerStore, setSchedulerStore, createScheduledTask, listScheduledTasks, getScheduledTask, cancelScheduledTask, pauseScheduledTask, resumeScheduledTask, runScheduledTaskNow, deleteScheduledTask, nextScheduledWakeAt, moveScheduledTasksToTimeZone, importLegacyScheduledTasks, parseEvery, describeSchedule, type ScheduledTask, type ScheduledTaskRun, type ScheduledTaskStatus, type Schedule, type SchedulerStore, type FireTask, type CreateScheduledTaskInput } from '#core/scheduler.js';
 export { NOTIFIER_SLACK_SIGNING_SECRET_VAR } from '#core/notifier-file.js';
 export { firstSighting, handleInboundMessage, handleMessagingAction, settleThreadChoice, isPlainApproval, type MessagingDeps, type MessagingDecision, type DecisionOutcome } from '#core/messaging/engine.js';
 export { formatArgs, formatChange, labelFor } from '#core/messaging/format-args.js';
@@ -88,10 +88,11 @@ export { installAbility, upgradeAbility, removeAbility, listInstalledAbilities,
 export type { InstalledAbilityRecord, AbilityEnvDecl, UpgradeFileResult } from './bin/ability-manager.js';
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';
 export type { PublicAbilitySearchResult } from './web/abilities-admin.js';
-export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError } from './web/global-config.js';
+export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError, describeTimeZone, setWorkspaceTimeZone, TimeZoneError } from './web/global-config.js';
 export { loopengineVersion } from './core/version.js';
 export { describeUpgrade, runUpgrade, UpgradeError } from './web/upgrade-admin.js';
-export type { ModelProviderInfo, AgentModelUsage, ModelsView, GatewayProviderInfo, GatewaysView } from './web/global-config.js';
+export type { ModelProviderInfo, AgentModelUsage, ModelsView, GatewayProviderInfo, GatewaysView, TimeZoneView } from './web/global-config.js';
+export { workspaceTimeZone, serverTimeZone, isValidTimeZone, TIME_ZONE_ENV } from '#core/time-zone.js';
 export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
 export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';
 export type { AgentTemplateOptions } from './bin/cli.js';

package/dist/index.js

@@ -12,7 +12,7 @@ export { setUsageSink, recordUsage } from '#core/usage.js';
 export { readNotifierFile, writeNotifierFile, removeNotifierFile, validateNotifierFile, notifierConfigFromFile, NotifierFileError, NOTIFIER_SECRET_VARS } from '#core/notifier-file.js';
 export { listDeliveries, recordDelivery } from '#core/notifier-deliveries.js';
 export { describeNotifier } from '#core/http-notifier.js';
-export { Scheduler, ScheduleError, FileSchedulerStore, getSchedulerStore, setSchedulerStore, createScheduledTask, listScheduledTasks, getScheduledTask, cancelScheduledTask, pauseScheduledTask, resumeScheduledTask, runScheduledTaskNow, deleteScheduledTask, nextScheduledWakeAt, importLegacyScheduledTasks, parseEvery, describeSchedule } from '#core/scheduler.js';
+export { Scheduler, ScheduleError, FileSchedulerStore, getSchedulerStore, setSchedulerStore, createScheduledTask, listScheduledTasks, getScheduledTask, cancelScheduledTask, pauseScheduledTask, resumeScheduledTask, runScheduledTaskNow, deleteScheduledTask, nextScheduledWakeAt, moveScheduledTasksToTimeZone, importLegacyScheduledTasks, parseEvery, describeSchedule } from '#core/scheduler.js';
 export { NOTIFIER_SLACK_SIGNING_SECRET_VAR } from '#core/notifier-file.js';
 export { firstSighting, handleInboundMessage, handleMessagingAction, settleThreadChoice, isPlainApproval } from '#core/messaging/engine.js';
 export { formatArgs, formatChange, labelFor } from '#core/messaging/format-args.js';
@@ -78,8 +78,9 @@ export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, setAgentEnvVar, unsetAgent
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export { installAbility, upgradeAbility, removeAbility, listInstalledAbilities, backfillDependencies, AbilityManifestError, AbilityVersionError, AbilityCollisionError, AbilityAlreadyInstalledError, AbilityNotInstalledError, } from './bin/ability-manager.js';
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';
-export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError } from './web/global-config.js';
+export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError, describeTimeZone, setWorkspaceTimeZone, TimeZoneError } from './web/global-config.js';
 export { loopengineVersion } from './core/version.js';
 export { describeUpgrade, runUpgrade, UpgradeError } from './web/upgrade-admin.js';
+export { workspaceTimeZone, serverTimeZone, isValidTimeZone, TIME_ZONE_ENV } from '#core/time-zone.js';
 export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
 export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';