chainlesschain 0.163.5 → 0.163.6

package/src/lib/agent-schedule-store.js

@@ -185,7 +185,9 @@ function applyScheduledAgentSuccess(entry, atMs) {
   if (entry.kind === "cron") {
     entry.lastRunAt = atMs;
     entry.runs = (entry.runs || 0) + 1;
-    const next = nextCronTime(entry.cron, atMs);
+    const next = nextCronTime(entry.cron, atMs, {
+      timeZone: entry.timeZone || null,
+    });
     if (next == null) entry.status = "exhausted";
     else entry.nextAt = next;
     return;
@@ -196,6 +198,51 @@ function applyScheduledAgentSuccess(entry, atMs) {
   );
 }
 
+function applyScheduledMonitorSuccess(entry, monitorCheck, atMs) {
+  if (
+    entry.kind !== "monitor" ||
+    !monitorCheck ||
+    typeof monitorCheck !== "object" ||
+    Array.isArray(monitorCheck) ||
+    typeof monitorCheck.matched !== "boolean"
+  ) {
+    throw agendaStoreError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Scheduler monitor result is invalid: ${entry.id}`,
+    );
+  }
+  const mtimeMs =
+    monitorCheck.mtimeMs === null || monitorCheck.mtimeMs === undefined
+      ? null
+      : Number(monitorCheck.mtimeMs);
+  if (mtimeMs !== null && (!Number.isFinite(mtimeMs) || mtimeMs < 0)) {
+    throw agendaStoreError(
+      "AGENDA_SCHEDULER_MONITOR_RESULT_INVALID",
+      `Scheduler monitor mtime is invalid: ${entry.id}`,
+    );
+  }
+  entry.checks = (entry.checks || 0) + 1;
+  entry.lastCheckAt = atMs;
+  if (mtimeMs !== null && entry.lastMtimeMs == null) {
+    entry.lastMtimeMs = mtimeMs;
+  }
+  if (monitorCheck.matched) {
+    entry.status = "matched";
+    entry.matchedAt = atMs;
+    if (monitorCheck.eventId != null) {
+      entry.lastEventId = String(monitorCheck.eventId);
+      entry.lastEventAt = atMs;
+    }
+    if (monitorCheck.authority != null) {
+      entry.lastAuthority = String(monitorCheck.authority);
+    }
+  } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
+    entry.status = "exhausted";
+  } else {
+    entry.nextAt = atMs + entry.intervalMs;
+  }
+}
+
 /** Statuses an entry can never leave — safe to prune. */
 export const TERMINAL_STATUSES = Object.freeze([
   "fired",
@@ -232,6 +279,61 @@ const CRON_RANGES = [
   [0, 6], // day of week (0/7 = Sunday)
 ];
 
+const CRON_TIME_ZONE_FORMATTERS = new Map();
+
+export function normalizeTimeZone(value) {
+  if (value == null || value === "") return null;
+  if (typeof value !== "string") {
+    throw new Error("cron timeZone must be an IANA time zone string");
+  }
+  const requested = value.trim();
+  if (!requested) return null;
+  if (requested.length > 128 || /\p{Cc}/u.test(requested)) {
+    throw new Error("invalid IANA time zone");
+  }
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: requested,
+    }).resolvedOptions().timeZone;
+  } catch {
+    throw new Error(`invalid IANA time zone: ${requested}`);
+  }
+}
+
+function timeZoneFormatter(timeZone) {
+  let formatter = CRON_TIME_ZONE_FORMATTERS.get(timeZone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US-u-ca-gregory-nu-latn", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    });
+    CRON_TIME_ZONE_FORMATTERS.set(timeZone, formatter);
+  }
+  return formatter;
+}
+
+function timeZoneParts(epochMs, timeZone) {
+  const values = {};
+  for (const part of timeZoneFormatter(timeZone).formatToParts(epochMs)) {
+    if (part.type !== "literal") values[part.type] = Number(part.value);
+  }
+  return {
+    year: values.year,
+    minute: values.minute,
+    hour: values.hour,
+    day: values.day,
+    month: values.month,
+    dayOfWeek: new Date(
+      Date.UTC(values.year, values.month - 1, values.day),
+    ).getUTCDay(),
+  };
+}
+
 function parseCronField(field, [min, max]) {
   const values = new Set();
   for (const part of String(field).split(",")) {
@@ -280,13 +382,175 @@ function cronMatches(sets, date) {
   );
 }
 
+function timeZoneOffsetAt(epochMs, timeZone) {
+  const minuteEpoch = Math.floor(epochMs / 60_000) * 60_000;
+  const parts = timeZoneParts(minuteEpoch, timeZone);
+  return (
+    Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute) -
+    minuteEpoch
+  );
+}
+
+function localDayOffsets(year, month, day, timeZone) {
+  const reference = Date.UTC(year, month - 1, day, 12, 0, 0);
+  return [
+    ...new Set(
+      [-36, -12, 0, 12, 36].map((hours) =>
+        timeZoneOffsetAt(reference + hours * 3_600_000, timeZone),
+      ),
+    ),
+  ];
+}
+
+function epochCandidatesForCivilMinute(
+  { year, month, day, hour, minute },
+  timeZone,
+  offsets,
+) {
+  const civilEpoch = Date.UTC(year, month - 1, day, hour, minute, 0);
+  const matches = [];
+  for (const offset of offsets) {
+    const epoch = civilEpoch - offset;
+    const actual = timeZoneParts(epoch, timeZone);
+    if (
+      actual.year === year &&
+      actual.month === month &&
+      actual.day === day &&
+      actual.hour === hour &&
+      actual.minute === minute
+    ) {
+      matches.push(epoch);
+    }
+  }
+  return [...new Set(matches)].sort((a, b) => a - b);
+}
+
+function nextCronTimeInTimeZone(sets, fromMs, timeZone) {
+  const from = Number(fromMs);
+  const firstLocal = timeZoneParts(from, timeZone);
+  const firstLocalDay = Date.UTC(
+    firstLocal.year,
+    firstLocal.month - 1,
+    firstLocal.day,
+  );
+  const minuteLimit = 366 * 24 * 60;
+  const lastEpoch = Math.floor(from / 60_000) * 60_000 + minuteLimit * 60_000;
+  const hours = [...sets[1]].sort((a, b) => a - b);
+  const minutes = [...sets[0]].sort((a, b) => a - b);
+  let earliest = null;
+
+  // Iterate civil dates instead of formatting every real minute. At most two
+  // UTC offsets can map a civil minute around a DST transition; verifying each
+  // reconstructed candidate preserves missing and repeated wall-time behavior.
+  // Start one civil day earlier because a rare midnight rollback can make a
+  // future real instant display as the previous local date. Once a later civil
+  // date is more than 36 hours beyond the best epoch, no supported IANA offset
+  // can map that date back before the current best candidate.
+  for (let dayOffset = -1; dayOffset <= 367; dayOffset += 1) {
+    const civilDay = firstLocalDay + dayOffset * 86_400_000;
+    if (earliest != null && civilDay - 36 * 3_600_000 > earliest) break;
+    const date = new Date(civilDay);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const day = date.getUTCDate();
+    const dayOfWeek = date.getUTCDay();
+    if (
+      !sets[2].has(day) ||
+      !sets[3].has(month) ||
+      (!sets[4].has(dayOfWeek) && !(sets[4].has(7) && dayOfWeek === 0))
+    ) {
+      continue;
+    }
+    const offsets = localDayOffsets(year, month, day, timeZone);
+    for (const hour of hours) {
+      for (const minute of minutes) {
+        for (const epoch of epochCandidatesForCivilMinute(
+          { year, month, day, hour, minute },
+          timeZone,
+          offsets,
+        )) {
+          if (
+            epoch > from &&
+            epoch <= lastEpoch &&
+            (earliest == null || epoch < earliest)
+          ) {
+            earliest = epoch;
+          }
+        }
+      }
+    }
+  }
+  return earliest;
+}
+
+function previousCronTimeInTimeZone(sets, fromMs, timeZone) {
+  const from = Number(fromMs);
+  const firstLocal = timeZoneParts(from, timeZone);
+  const firstLocalDay = Date.UTC(
+    firstLocal.year,
+    firstLocal.month - 1,
+    firstLocal.day,
+  );
+  const minuteLimit = 366 * 24 * 60;
+  const firstEpoch = Math.floor(from / 60_000) * 60_000 - minuteLimit * 60_000;
+  const hours = [...sets[1]].sort((a, b) => b - a);
+  const minutes = [...sets[0]].sort((a, b) => b - a);
+  let latest = null;
+
+  // Start one civil day ahead because a rare midnight transition can make a
+  // prior real instant display as the following local date.
+  for (let dayOffset = 1; dayOffset >= -367; dayOffset -= 1) {
+    const civilDay = firstLocalDay + dayOffset * 86_400_000;
+    if (latest != null && civilDay + 36 * 3_600_000 < latest) break;
+    const date = new Date(civilDay);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const day = date.getUTCDate();
+    const dayOfWeek = date.getUTCDay();
+    if (
+      !sets[2].has(day) ||
+      !sets[3].has(month) ||
+      (!sets[4].has(dayOfWeek) && !(sets[4].has(7) && dayOfWeek === 0))
+    ) {
+      continue;
+    }
+    const offsets = localDayOffsets(year, month, day, timeZone);
+    for (const hour of hours) {
+      for (const minute of minutes) {
+        for (const epoch of epochCandidatesForCivilMinute(
+          { year, month, day, hour, minute },
+          timeZone,
+          offsets,
+        )) {
+          if (
+            epoch < from &&
+            epoch >= firstEpoch &&
+            (latest == null || epoch > latest)
+          ) {
+            latest = epoch;
+          }
+        }
+      }
+    }
+  }
+  return latest;
+}
+
 /**
- * Next epoch-ms at which `expr` fires strictly after `fromMs` (local time,
- * minute granularity). Scans up to ~366 days then gives up (returns null) so a
- * never-matching expression can't loop forever.
+ * Next epoch-ms at which `expr` fires strictly after `fromMs`, at minute
+ * granularity. By default this preserves host-local cron behavior; an explicit
+ * IANA `timeZone` evaluates the same epoch minutes against that civil clock.
+ * A repeated fall-back wall minute therefore maps to both real instants, while
+ * a skipped spring-forward wall minute does not exist. Scans up to ~366 days
+ * then gives up (returns null) so a never-matching expression can't loop
+ * forever.
  */
-export function nextCronTime(expr, fromMs) {
+export function nextCronTime(expr, fromMs, options = {}) {
   const sets = parseCron(expr);
+  const timeZone = normalizeTimeZone(
+    typeof options === "string" ? options : options?.timeZone,
+  );
+  if (timeZone) return nextCronTimeInTimeZone(sets, fromMs, timeZone);
   const cursor = new Date(fromMs);
   cursor.setSeconds(0, 0);
   cursor.setMinutes(cursor.getMinutes() + 1);
@@ -298,6 +562,25 @@ export function nextCronTime(expr, fromMs) {
   return null;
 }
 
+/** Previous cron occurrence strictly before `fromMs`, bounded to one year. */
+export function previousCronTime(expr, fromMs, options = {}) {
+  const sets = parseCron(expr);
+  const timeZone = normalizeTimeZone(
+    typeof options === "string" ? options : options?.timeZone,
+  );
+  if (timeZone) return previousCronTimeInTimeZone(sets, fromMs, timeZone);
+  const cursor = new Date(fromMs);
+  cursor.setSeconds(0, 0);
+  if (cursor.getTime() >= Number(fromMs))
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  const limit = 366 * 24 * 60;
+  for (let i = 0; i < limit; i += 1) {
+    if (cronMatches(sets, cursor)) return cursor.getTime();
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  }
+  return null;
+}
+
 // ─── store ───────────────────────────────────────────────────────────────
 
 export class AgentScheduleStore {
@@ -390,12 +673,16 @@ export class AgentScheduleStore {
       expiresAt = null,
       expiresInMs = null,
       jitterMs = 0,
+      timeZone = null,
     } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("cron requires a prompt");
     }
     const now = this._now();
-    const nextAt = nextCronTime(cron, now); // validates the expression too
+    const normalizedTimeZone = normalizeTimeZone(timeZone);
+    const nextAt = nextCronTime(cron, now, {
+      timeZone: normalizedTimeZone,
+    }); // validates the expression and optional IANA time zone
     if (nextAt == null) {
       throw new Error(`cron "${cron}" has no upcoming match`);
     }
@@ -406,6 +693,7 @@ export class AgentScheduleStore {
       kind: "cron",
       prompt,
       cron,
+      ...(normalizedTimeZone ? { timeZone: normalizedTimeZone } : {}),
       label: label || null,
       nextAt,
       expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
@@ -609,7 +897,7 @@ export class AgentScheduleStore {
   }
 
   /**
-   * Bind a scheduler claim to the legacy Agenda entry before agent execution.
+   * Bind a scheduler claim to the legacy Agenda entry before execution.
    * The same lock used by legacy `claimDue()` prevents an old/new driver from
    * starting the entry concurrently during migration.
    */
@@ -640,7 +928,7 @@ export class AgentScheduleStore {
     return withFileLock(
       path.join(this.dir, ".agenda-claims"),
       () => {
-        for (const kind of ["wakeup", "cron"]) {
+        for (const kind of SCHEDULE_KINDS) {
           const entries = this._readAll(kind);
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
@@ -678,7 +966,8 @@ export class AgentScheduleStore {
           // Fence an older CLI that only understands the legacy claim field.
           // Terminal scheduler evidence clears this lease; an outcome-unknown
           // execution intentionally keeps it non-expiring until adjudicated so
-          // an old runner cannot duplicate an uncertain agent side effect.
+          // an old runner cannot duplicate an uncertain external observation or
+          // agent side effect.
           entry.executionLease = {
             owner: `scheduler:${occurrenceId}:${attempt}`,
             claimedAt: now,
@@ -697,10 +986,10 @@ export class AgentScheduleStore {
   }
 
   /**
-   * Atomically publish scheduler evidence and the legacy wakeup/cron state.
-   * A successful cron advances exactly once in the same JSONL replacement that
-   * records terminal evidence; failures keep the entry schedulable for the
-   * scheduler kernel's bounded retry policy.
+   * Atomically publish scheduler evidence and the legacy Agenda state. A
+   * successful cron advances and a successful monitor records/re-arms exactly
+   * once in the same JSONL replacement that records terminal evidence;
+   * failures keep the entry schedulable for the kernel's bounded retry policy.
    */
   completeSchedulerExecution(
     id,
@@ -711,6 +1000,7 @@ export class AgentScheduleStore {
       outcome,
       result = null,
       error = null,
+      monitorCheck = null,
       atMs = null,
     } = {},
   ) {
@@ -725,7 +1015,7 @@ export class AgentScheduleStore {
     return withFileLock(
       path.join(this.dir, ".agenda-claims"),
       () => {
-        for (const kind of ["wakeup", "cron"]) {
+        for (const kind of SCHEDULE_KINDS) {
           const entries = this._readAll(kind);
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
@@ -742,14 +1032,23 @@ export class AgentScheduleStore {
               `Agenda scheduler evidence does not match the active claim: ${id}`,
             );
           }
+          let storedResult = result;
           if (outcome === "succeeded") {
-            applyScheduledAgentSuccess(entry, now);
+            if (entry.kind === "monitor") {
+              applyScheduledMonitorSuccess(entry, monitorCheck, now);
+              storedResult =
+                result && typeof result === "object" && !Array.isArray(result)
+                  ? { ...result, status: entry.status }
+                  : result;
+            } else {
+              applyScheduledAgentSuccess(entry, now);
+            }
           }
           entry.schedulerExecution = {
             ...evidence,
             status: outcome,
             endedAt: now,
-            ...(outcome === "succeeded" ? { result } : { error }),
+            ...(outcome === "succeeded" ? { result: storedResult } : { error }),
           };
           delete entry.executionLease;
           this._writeAll(kind, entries);
@@ -841,7 +1140,9 @@ export class AgentScheduleStore {
     return this._mutate("cron", id, (entry) => {
       entry.lastRunAt = now;
       entry.runs = (entry.runs || 0) + 1;
-      const next = nextCronTime(entry.cron, now);
+      const next = nextCronTime(entry.cron, now, {
+        timeZone: entry.timeZone || null,
+      });
       if (next == null) {
         entry.status = "exhausted";
       } else {
@@ -866,32 +1167,11 @@ export class AgentScheduleStore {
   ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
-      entry.checks = (entry.checks || 0) + 1;
-      entry.lastCheckAt = now;
-      // Record the mtime baseline the first time we see the file (for a
-      // watchChange monitor); leave it fixed thereafter so "changed" always
-      // means "changed since we started watching".
-      if (mtimeMs != null && entry.lastMtimeMs == null) {
-        entry.lastMtimeMs = mtimeMs;
-      }
-      if (matched) {
-        entry.status = "matched";
-        entry.matchedAt = now;
-        // Audit record of the firing: the deterministic monitor-event id + the
-        // (always SYSTEM/steer) authority the event was delivered under. Durable
-        // on the entry so `cc agenda list --json` and a future resident daemon
-        // can recognise / dedup the exact observation. Only stamped when the
-        // caller supplies them, so legacy callers stay byte-identical.
-        if (eventId != null) {
-          entry.lastEventId = String(eventId);
-          entry.lastEventAt = now;
-        }
-        if (authority != null) entry.lastAuthority = String(authority);
-      } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
-        entry.status = "exhausted";
-      } else {
-        entry.nextAt = now + entry.intervalMs;
-      }
+      applyScheduledMonitorSuccess(
+        entry,
+        { matched: Boolean(matched), mtimeMs, eventId, authority },
+        now,
+      );
     });
   }