chainlesschain 0.163.4 → 0.163.6

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

@@ -168,6 +168,81 @@ function hasLiveExecutionLease(entry, now) {
   return Number(entry.executionLease?.expiresAt) > Number(now);
 }
 
+function agendaStoreError(code, message, { retryable = false, retryAt } = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.retryable = retryable;
+  if (retryAt !== undefined) error.retryAt = retryAt;
+  return error;
+}
+
+function applyScheduledAgentSuccess(entry, atMs) {
+  if (entry.kind === "wakeup") {
+    entry.status = "fired";
+    entry.firedAt = atMs;
+    return;
+  }
+  if (entry.kind === "cron") {
+    entry.lastRunAt = atMs;
+    entry.runs = (entry.runs || 0) + 1;
+    const next = nextCronTime(entry.cron, atMs, {
+      timeZone: entry.timeZone || null,
+    });
+    if (next == null) entry.status = "exhausted";
+    else entry.nextAt = next;
+    return;
+  }
+  throw agendaStoreError(
+    "AGENDA_SCHEDULER_KIND_UNSUPPORTED",
+    `Scheduler execution is not supported for agenda kind: ${entry.kind}`,
+  );
+}
+
+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",
@@ -204,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(",")) {
@@ -252,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);
@@ -270,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 {
@@ -362,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`);
     }
@@ -378,6 +693,7 @@ export class AgentScheduleStore {
       kind: "cron",
       prompt,
       cron,
+      ...(normalizedTimeZone ? { timeZone: normalizedTimeZone } : {}),
       label: label || null,
       nextAt,
       expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
@@ -499,6 +815,11 @@ export class AgentScheduleStore {
     return out;
   }
 
+  get(id) {
+    if (typeof id !== "string" || id.length === 0) return null;
+    return this.list().find((entry) => entry.id === id) || null;
+  }
+
   /** Entries whose time has come (pending wakeup / active cron|monitor). */
   due(kind = null, atMs = null) {
     const now = atMs != null ? atMs : this._now();
@@ -524,16 +845,20 @@ export class AgentScheduleStore {
    * lease expires. This is deliberately separate from `due()` for backwards
    * compatibility with read-only callers and injected test stores.
    */
-  claimDue(atMs = null, leaseMs = 120000) {
+  claimDue(atMs = null, leaseMs = 120000, kind = null) {
     const now = atMs != null ? Number(atMs) : this._now();
     const ttl = Math.max(1000, Number(leaseMs) || 120000);
+    const kinds = kind == null ? SCHEDULE_KINDS : [kind];
+    if (kinds.some((value) => !SCHEDULE_KINDS.includes(value))) {
+      throw new Error(`unknown schedule kind: ${kind}`);
+    }
     this._ensureDir();
     return withFileLock(
       path.join(this.dir, ".agenda-claims"),
       () => {
         const claimed = [];
-        for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+        for (const scheduleKind of kinds) {
+          const entries = this._readAll(scheduleKind);
           let changed = false;
           for (const entry of entries) {
             if (!isSchedulableStatus(entry) || isEntryExpired(entry, now))
@@ -552,7 +877,7 @@ export class AgentScheduleStore {
             });
             changed = true;
           }
-          if (changed) this._writeAll(kind, entries);
+          if (changed) this._writeAll(scheduleKind, entries);
         }
         return claimed;
       },
@@ -571,6 +896,173 @@ export class AgentScheduleStore {
     return null;
   }
 
+  /**
+   * 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.
+   */
+  bindSchedulerExecution(
+    id,
+    { occurrenceId, snapshotDigest, attempt, atMs = null } = {},
+  ) {
+    const now = atMs != null ? Number(atMs) : this._now();
+    if (typeof occurrenceId !== "string" || occurrenceId.length === 0) {
+      throw agendaStoreError(
+        "AGENDA_SCHEDULER_BINDING_INVALID",
+        "Agenda scheduler occurrenceId is required",
+      );
+    }
+    if (typeof snapshotDigest !== "string" || snapshotDigest.length === 0) {
+      throw agendaStoreError(
+        "AGENDA_SCHEDULER_BINDING_INVALID",
+        "Agenda scheduler snapshotDigest is required",
+      );
+    }
+    if (!Number.isSafeInteger(attempt) || attempt < 1) {
+      throw agendaStoreError(
+        "AGENDA_SCHEDULER_BINDING_INVALID",
+        "Agenda scheduler attempt must be a positive integer",
+      );
+    }
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          const prior = entry.schedulerExecution;
+          if (prior?.status === "running") {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_OUTCOME_UNKNOWN",
+              `Agenda scheduler execution outcome is unknown: ${id}`,
+            );
+          }
+          if (
+            prior?.status === "succeeded" &&
+            prior.occurrenceId === occurrenceId &&
+            prior.snapshotDigest === snapshotDigest
+          ) {
+            return entry;
+          }
+          if (hasLiveExecutionLease(entry, now)) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_LEGACY_CLAIM_ACTIVE",
+              `Agenda entry is already claimed by a legacy runner: ${id}`,
+              {
+                retryable: true,
+                retryAt: Number(entry.executionLease.expiresAt),
+              },
+            );
+          }
+          entry.schedulerExecution = {
+            occurrenceId,
+            snapshotDigest,
+            attempt,
+            status: "running",
+            startedAt: now,
+          };
+          // 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 external observation or
+          // agent side effect.
+          entry.executionLease = {
+            owner: `scheduler:${occurrenceId}:${attempt}`,
+            claimedAt: now,
+            expiresAt: Number.MAX_SAFE_INTEGER,
+          };
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
+  /**
+   * 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,
+    {
+      occurrenceId,
+      snapshotDigest,
+      attempt,
+      outcome,
+      result = null,
+      error = null,
+      monitorCheck = null,
+      atMs = null,
+    } = {},
+  ) {
+    if (!["succeeded", "failed"].includes(outcome)) {
+      throw agendaStoreError(
+        "AGENDA_SCHEDULER_OUTCOME_INVALID",
+        "Agenda scheduler outcome must be succeeded or failed",
+      );
+    }
+    const now = atMs != null ? Number(atMs) : this._now();
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".agenda-claims"),
+      () => {
+        for (const kind of SCHEDULE_KINDS) {
+          const entries = this._readAll(kind);
+          const entry = entries.find((candidate) => candidate.id === id);
+          if (!entry) continue;
+          const evidence = entry.schedulerExecution;
+          if (
+            !evidence ||
+            evidence.occurrenceId !== occurrenceId ||
+            evidence.snapshotDigest !== snapshotDigest ||
+            evidence.attempt !== attempt ||
+            evidence.status !== "running"
+          ) {
+            throw agendaStoreError(
+              "AGENDA_SCHEDULER_BINDING_MISMATCH",
+              `Agenda scheduler evidence does not match the active claim: ${id}`,
+            );
+          }
+          let storedResult = result;
+          if (outcome === "succeeded") {
+            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: storedResult } : { error }),
+          };
+          delete entry.executionLease;
+          this._writeAll(kind, entries);
+          return entry;
+        }
+        throw agendaStoreError(
+          "AGENDA_SCHEDULER_ENTRY_NOT_FOUND",
+          `Agenda entry does not exist: ${id}`,
+        );
+      },
+      { failIfUnavailable: true },
+    );
+  }
+
   /**
    * Retire every schedulable entry whose `expiresAt` has passed (status →
    * "expired", stamping `expiredAt`), across all kinds, so it never fires again.
@@ -648,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 {
@@ -673,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,
+      );
     });
   }