feat: add heartbeat active hours

src/infra/heartbeat-runner.returns-default-unset.test.ts

@@ -300,6 +300,30 @@ describe("runHeartbeatOnce", () => {
     }
   });
 
+  it("skips outside active hours", async () => {
+    const cfg: ClawdbotConfig = {
+      agents: {
+        defaults: {
+          userTimezone: "UTC",
+          heartbeat: {
+            every: "30m",
+            activeHours: { start: "08:00", end: "24:00", timezone: "user" },
+          },
+        },
+      },
+    };
+
+    const res = await runHeartbeatOnce({
+      cfg,
+      deps: { nowMs: () => Date.UTC(2025, 0, 1, 7, 0, 0) },
+    });
+
+    expect(res.status).toBe("skipped");
+    if (res.status === "skipped") {
+      expect(res.reason).toBe("quiet-hours");
+    }
+  });
+
   it("uses the last non-empty payload for delivery", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-"));
     const storePath = path.join(tmpDir, "sessions.json");

src/infra/heartbeat-runner.ts

@@ -1,4 +1,5 @@
 import { resolveAgentConfig, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { resolveUserTimezone } from "../agents/date-time.js";
 import { resolveEffectiveMessagesConfig } from "../agents/identity.js";
 import {
   DEFAULT_HEARTBEAT_ACK_MAX_CHARS,
@@ -69,6 +70,81 @@ export type HeartbeatSummary = {
 };
 
 const DEFAULT_HEARTBEAT_TARGET = "last";
+const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;
+
+function resolveActiveHoursTimezone(cfg: ClawdbotConfig, raw?: string): string {
+  const trimmed = raw?.trim();
+  if (!trimmed || trimmed === "user") {
+    return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
+  }
+  if (trimmed === "local") {
+    const host = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return host?.trim() || "UTC";
+  }
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format(new Date());
+    return trimmed;
+  } catch {
+    return resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
+  }
+}
+
+function parseActiveHoursTime(raw?: string, opts: { allow24: boolean }): number | null {
+  if (!raw || !ACTIVE_HOURS_TIME_PATTERN.test(raw)) return null;
+  const [hourStr, minuteStr] = raw.split(":");
+  const hour = Number(hourStr);
+  const minute = Number(minuteStr);
+  if (!Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+  if (hour === 24) {
+    if (!opts.allow24 || minute !== 0) return null;
+    return 24 * 60;
+  }
+  return hour * 60 + minute;
+}
+
+function resolveMinutesInTimeZone(nowMs: number, timeZone: string): number | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(new Date(nowMs));
+    const map: Record<string, string> = {};
+    for (const part of parts) {
+      if (part.type !== "literal") map[part.type] = part.value;
+    }
+    const hour = Number(map.hour);
+    const minute = Number(map.minute);
+    if (!Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+    return hour * 60 + minute;
+  } catch {
+    return null;
+  }
+}
+
+function isWithinActiveHours(
+  cfg: ClawdbotConfig,
+  heartbeat?: HeartbeatConfig,
+  nowMs?: number,
+): boolean {
+  const active = heartbeat?.activeHours;
+  if (!active) return true;
+
+  const startMin = parseActiveHoursTime(active.start, { allow24: false });
+  const endMin = parseActiveHoursTime(active.end, { allow24: true });
+  if (startMin === null || endMin === null) return true;
+  if (startMin === endMin) return true;
+
+  const timeZone = resolveActiveHoursTimezone(cfg, active.timezone);
+  const currentMin = resolveMinutesInTimeZone(nowMs ?? Date.now(), timeZone);
+  if (currentMin === null) return true;
+
+  if (endMin > startMin) {
+    return currentMin >= startMin && currentMin < endMin;
+  }
+  return currentMin >= startMin || currentMin < endMin;
+}
 
 type HeartbeatAgentState = {
   agentId: string;
@@ -341,12 +417,16 @@ export async function runHeartbeatOnce(opts: {
     return { status: "skipped", reason: "disabled" };
   }
 
+  const startedAt = opts.deps?.nowMs?.() ?? Date.now();
+  if (!isWithinActiveHours(cfg, heartbeat, startedAt)) {
+    return { status: "skipped", reason: "quiet-hours" };
+  }
+
   const queueSize = (opts.deps?.getQueueSize ?? getQueueSize)(CommandLane.Main);
   if (queueSize > 0) {
     return { status: "skipped", reason: "requests-in-flight" };
   }
 
-  const startedAt = opts.deps?.nowMs?.() ?? Date.now();
   const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId);
   const previousUpdatedAt = entry?.updatedAt;
   const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });