@cohortapp/agent-sdk 2.3.0

package/lib/scheduling/dynamic-jobs.test.mjs

@@ -0,0 +1,344 @@
+/**
+ * dynamic-jobs.test.mjs — node:test coverage for agent-created scheduled jobs.
+ *
+ * Every test gets its own AGENT_ROOT under tmpdir() and cleans up. Time is
+ * always injected via `now` so the suite is hermetic and offline. Real
+ * assertions: parseWhen output, persistence, cancel, and the coalescing /
+ * TTL / notBefore firing decision.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import {
+  parseWhen,
+  nextCronAfter,
+  createJob,
+  listJobs,
+  cancelJob,
+  deferJob,
+  dueJobs,
+  readStore,
+  getJobsPath,
+  JOBS_RELATIVE,
+  DEFAULT_TTL_MS,
+} from "./dynamic-jobs.mjs";
+
+// 2026-06-10T12:00:00Z is a Wednesday — the fixed reference clock.
+const WED_NOON = Date.UTC(2026, 5, 10, 12, 0, 0);
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `dynamic-jobs-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+// ---------------------------------------------------------------------------
+// parseWhen
+// ---------------------------------------------------------------------------
+
+test("parseWhen: 'Friday 9am' resolves to the next Friday 9am one-off", () => {
+  const r = parseWhen("remind X Friday 9am", { now: WED_NOON, tz: "UTC" });
+  assert.ok(r && typeof r.at === "number", "should be a one-off {at}");
+  const d = new Date(r.at);
+  assert.equal(d.getUTCDay(), 5, "Friday");
+  assert.equal(d.getUTCHours(), 9);
+  assert.equal(d.getUTCMinutes(), 0);
+  // From Wed Jun 10 → Fri Jun 12.
+  assert.equal(d.toISOString(), "2026-06-12T09:00:00.000Z");
+  assert.equal(r.tz, "UTC");
+});
+
+test("parseWhen: 'every weekday 8am' is a recurring cron Mon-Fri", () => {
+  const r = parseWhen("every weekday 8am summarize the channel", { now: WED_NOON, tz: "UTC" });
+  assert.ok(r && r.cron, "should be recurring {cron}");
+  assert.equal(r.cron, "0 8 * * 1-5");
+});
+
+test("parseWhen: 'in 2 hours' is a relative one-off", () => {
+  const r = parseWhen("ping me in 2 hours", { now: WED_NOON, tz: "UTC" });
+  assert.equal(r.at, WED_NOON + 2 * 60 * 60 * 1000);
+  assert.equal(new Date(r.at).toISOString(), "2026-06-10T14:00:00.000Z");
+});
+
+test("parseWhen: relative units (min/day/week)", () => {
+  assert.equal(parseWhen("in 30 minutes", { now: WED_NOON }).at, WED_NOON + 30 * 60_000);
+  assert.equal(parseWhen("in 3 days", { now: WED_NOON }).at, WED_NOON + 3 * 86_400_000);
+  assert.equal(parseWhen("in 1 week", { now: WED_NOON }).at, WED_NOON + 7 * 86_400_000);
+});
+
+test("parseWhen: timezone shifts the resolved instant", () => {
+  // 9am Dubai (+4) on Friday → 05:00Z.
+  const r = parseWhen("Friday 9am", { now: WED_NOON, tz: "Asia/Dubai" });
+  assert.equal(new Date(r.at).toISOString(), "2026-06-12T05:00:00.000Z");
+  assert.equal(r.tz, "Asia/Dubai");
+});
+
+test("parseWhen: recurring variants — daily, specific weekday, weekend", () => {
+  assert.equal(parseWhen("every day at 7am", { now: WED_NOON }).cron, "0 7 * * *");
+  assert.equal(parseWhen("daily 7am", { now: WED_NOON }).cron, "0 7 * * *");
+  assert.equal(parseWhen("every monday at 9am", { now: WED_NOON }).cron, "0 9 * * 1");
+  assert.equal(parseWhen("every weekend at 10am", { now: WED_NOON }).cron, "0 10 * * 0,6");
+});
+
+test("parseWhen: tomorrow/today and 24h clock", () => {
+  assert.equal(
+    new Date(parseWhen("tomorrow 9am", { now: WED_NOON }).at).toISOString(),
+    "2026-06-11T09:00:00.000Z"
+  );
+  // 24h time with no am/pm.
+  assert.equal(
+    new Date(parseWhen("today 14:30", { now: WED_NOON }).at).toISOString(),
+    "2026-06-10T14:30:00.000Z"
+  );
+  // noon / midnight keywords.
+  assert.equal(new Date(parseWhen("today noon", { now: WED_NOON }).at).getUTCHours(), 12);
+});
+
+test("parseWhen: bare time rolls to the next occurrence if already past", () => {
+  // It's noon; "9am" already passed today → resolves to tomorrow 9am.
+  const r = parseWhen("9am", { now: WED_NOON, tz: "UTC" });
+  assert.equal(new Date(r.at).toISOString(), "2026-06-11T09:00:00.000Z");
+});
+
+test("parseWhen: returns null for unparseable / empty input", () => {
+  assert.equal(parseWhen("", { now: WED_NOON }), null);
+  assert.equal(parseWhen("just some words", { now: WED_NOON }), null);
+  assert.equal(parseWhen(null), null);
+});
+
+// ---------------------------------------------------------------------------
+// nextCronAfter
+// ---------------------------------------------------------------------------
+
+test("nextCronAfter: weekday 8am from Wed noon → Thu 8am", () => {
+  const next = nextCronAfter("0 8 * * 1-5", WED_NOON, "UTC");
+  assert.equal(new Date(next).toISOString(), "2026-06-11T08:00:00.000Z");
+});
+
+test("nextCronAfter: returns null for a malformed expression", () => {
+  assert.equal(nextCronAfter("not a cron", WED_NOON), null);
+  assert.equal(nextCronAfter("0 8 * *", WED_NOON), null); // 4 fields
+});
+
+// ---------------------------------------------------------------------------
+// createJob / listJobs / persistence
+// ---------------------------------------------------------------------------
+
+test("createJob persists a one-off to state/scheduling/jobs.json", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const when = parseWhen("Friday 9am", { now: WED_NOON, tz: "UTC" });
+    const job = createJob({ agentRoot: root, when, action: "reminder", payload: { who: "Sam" }, now: WED_NOON });
+    assert.equal(job.kind, "once");
+    assert.equal(job.action, "reminder");
+    assert.deepEqual(job.payload, { who: "Sam" });
+    assert.equal(job.status, "active");
+    assert.equal(job.next_run_at, when.at);
+
+    // On disk, atomically, at the expected path.
+    const path = getJobsPath(root);
+    assert.equal(path, join(root, JOBS_RELATIVE));
+    assert.ok(existsSync(path));
+    const onDisk = JSON.parse(readFileSync(path, "utf-8"));
+    assert.equal(onDisk.jobs.length, 1);
+    assert.equal(onDisk.jobs[0].id, job.id);
+  } finally { await rmRoot(root); }
+});
+
+test("createJob computes next_run_at for recurring cron jobs", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const when = parseWhen("every weekday 8am", { now: WED_NOON });
+    const job = createJob({ agentRoot: root, when, action: "summary", now: WED_NOON });
+    assert.equal(job.kind, "recurring");
+    assert.equal(job.cron, "0 8 * * 1-5");
+    // First fire is the next weekday 8am after now.
+    assert.equal(new Date(job.next_run_at).toISOString(), "2026-06-11T08:00:00.000Z");
+  } finally { await rmRoot(root); }
+});
+
+test("createJob rejects missing when/action", async () => {
+  const root = await makeAgentRoot();
+  try {
+    assert.throws(() => createJob({ agentRoot: root, action: "x" }), /when/);
+    assert.throws(() => createJob({ agentRoot: root, when: { at: 1 } }), /action/);
+  } finally { await rmRoot(root); }
+});
+
+test("listJobs returns active jobs only by default", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const a = createJob({ agentRoot: root, when: { at: WED_NOON + 1000 }, action: "a", now: WED_NOON });
+    createJob({ agentRoot: root, when: { at: WED_NOON + 2000 }, action: "b", now: WED_NOON });
+    cancelJob(root, a.id, { now: WED_NOON });
+    const active = listJobs(root);
+    assert.equal(active.length, 1);
+    assert.equal(active[0].action, "b");
+    assert.equal(listJobs(root, { all: true }).length, 2);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// cancelJob
+// ---------------------------------------------------------------------------
+
+test("cancelJob marks the job cancelled and stops it firing", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const job = createJob({ agentRoot: root, when: { at: WED_NOON - 1000 }, action: "reminder", now: WED_NOON });
+    assert.equal(cancelJob(root, job.id, { now: WED_NOON }), true);
+    // Cancelled → not returned by dueJobs even though it is past-due.
+    const fired = dueJobs(root, { now: WED_NOON });
+    assert.equal(fired.length, 0);
+    const stored = readStore(root).jobs[0];
+    assert.equal(stored.status, "cancelled");
+    assert.ok(stored.cancelled_at);
+    // Cancelling an unknown / already-cancelled id returns false.
+    assert.equal(cancelJob(root, job.id, { now: WED_NOON }), false);
+    assert.equal(cancelJob(root, "job-nope", { now: WED_NOON }), false);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// dueJobs — one-off firing + TTL
+// ---------------------------------------------------------------------------
+
+test("dueJobs fires a due one-off once, then marks it done", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const fireAt = WED_NOON;
+    createJob({ agentRoot: root, when: { at: fireAt }, action: "reminder", payload: { x: 1 }, now: WED_NOON - 1000 });
+    // Not yet due (1ms before).
+    assert.equal(dueJobs(root, { now: fireAt - 1 }).length, 0);
+    // Due now.
+    const fired = dueJobs(root, { now: fireAt });
+    assert.equal(fired.length, 1);
+    assert.deepEqual(fired[0].payload, { x: 1 });
+    // Fired once: a second poll returns nothing, job is done.
+    assert.equal(dueJobs(root, { now: fireAt + 1000 }).length, 0);
+    assert.equal(readStore(root).jobs[0].status, "done");
+  } finally { await rmRoot(root); }
+});
+
+test("dueJobs expires (does NOT fire) a one-off older than its TTL", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const fireAt = WED_NOON;
+    createJob({ agentRoot: root, when: { at: fireAt }, action: "reminder", ttlMs: 60_000, now: WED_NOON - 1000 });
+    // Poll well past the TTL — daemon was down. Must NOT deliver the stale job.
+    const fired = dueJobs(root, { now: fireAt + 5 * 60_000 });
+    assert.equal(fired.length, 0, "stale one-off must not fire late");
+    assert.equal(readStore(root).jobs[0].status, "expired");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// dueJobs — recurring coalescing (the missed-window-no-burst guarantee)
+// ---------------------------------------------------------------------------
+
+test("dueJobs coalesces a multi-day recurring outage into ONE fire", async () => {
+  const root = await makeAgentRoot();
+  try {
+    // Daily 8am job created Wed; first fire targets Thu Jun 11 08:00Z.
+    const when = parseWhen("every day at 8am", { now: WED_NOON });
+    const job = createJob({ agentRoot: root, when, action: "brief", now: WED_NOON });
+    assert.equal(new Date(job.next_run_at).toISOString(), "2026-06-11T08:00:00.000Z");
+
+    // Daemon was DOWN for three days. We come back online Sat Jun 13 at 09:00Z,
+    // having missed Thu, Fri, and Sat 08:00 windows.
+    const recover = Date.UTC(2026, 5, 13, 9, 0, 0);
+    const fired = dueJobs(root, { now: recover });
+    // Exactly ONE fire, not a burst of three.
+    assert.equal(fired.length, 1, "a 3-day outage must replay at most one brief");
+
+    // next_run_at fast-forwarded to the NEXT future boundary (Sun Jun 14 08:00).
+    const stored = readStore(root).jobs[0];
+    assert.equal(stored.status, "active");
+    assert.equal(new Date(stored.next_run_at).toISOString(), "2026-06-14T08:00:00.000Z");
+
+    // And a second immediate poll fires nothing (already coalesced forward).
+    assert.equal(dueJobs(root, { now: recover + 1000 }).length, 0);
+  } finally { await rmRoot(root); }
+});
+
+test("dueJobs fires a recurring job on each successive window (no premature fire)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const when = parseWhen("every day at 8am", { now: WED_NOON });
+    createJob({ agentRoot: root, when, action: "brief", now: WED_NOON });
+    const thu8 = Date.UTC(2026, 5, 11, 8, 0, 0);
+    const fri8 = Date.UTC(2026, 5, 12, 8, 0, 0);
+    // Before Thu 8am: nothing.
+    assert.equal(dueJobs(root, { now: thu8 - 60_000 }).length, 0);
+    // Thu 8am: fires.
+    assert.equal(dueJobs(root, { now: thu8 }).length, 1);
+    // Between Thu and Fri: nothing.
+    assert.equal(dueJobs(root, { now: thu8 + 6 * 3_600_000 }).length, 0);
+    // Fri 8am: fires again.
+    assert.equal(dueJobs(root, { now: fri8 }).length, 1);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// dueJobs — notBefore deferred redelivery
+// ---------------------------------------------------------------------------
+
+test("deferJob hides a due job until not_before, then it fires", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const fireAt = WED_NOON;
+    const job = createJob({ agentRoot: root, when: { at: fireAt }, action: "reminder", now: WED_NOON - 1000 });
+    // Consumer defers it 10 minutes (e.g. under load).
+    const notBefore = fireAt + 10 * 60_000;
+    assert.equal(deferJob(root, job.id, notBefore), true);
+
+    // Due by time, but suppressed by not_before.
+    assert.equal(dueJobs(root, { now: fireAt }).length, 0);
+    assert.equal(dueJobs(root, { now: notBefore - 1 }).length, 0);
+
+    // At not_before it becomes eligible and fires (within TTL).
+    const fired = dueJobs(root, { now: notBefore });
+    assert.equal(fired.length, 1);
+    // The defer marker is cleared on fire.
+    assert.equal(readStore(root).jobs[0].not_before, undefined);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Fail-open store reads
+// ---------------------------------------------------------------------------
+
+test("readStore fails open on a corrupt jobs.json", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const path = getJobsPath(root);
+    await fsp.mkdir(join(root, "state/scheduling"), { recursive: true });
+    await fsp.writeFile(path, "{ this is not json");
+    // Must not throw; reads as empty.
+    assert.deepEqual(readStore(root), { jobs: [] });
+    assert.deepEqual(dueJobs(root, { now: WED_NOON }), []);
+    // And we can still create on top of it (overwrites with a valid store).
+    const job = createJob({ agentRoot: root, when: { at: WED_NOON }, action: "x", now: WED_NOON });
+    assert.equal(readStore(root).jobs[0].id, job.id);
+  } finally { await rmRoot(root); }
+});
+
+test("DEFAULT_TTL_MS is the fallback one-off staleness window", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const job = createJob({ agentRoot: root, when: { at: WED_NOON }, action: "x", now: WED_NOON });
+    assert.equal(job.ttl_ms, DEFAULT_TTL_MS);
+  } finally { await rmRoot(root); }
+});

package/lib/scheduling/jitter.test.mjs

@@ -0,0 +1,140 @@
+/**
+ * jitter.test.mjs — node:test coverage for per-agent deterministic jitter.
+ *
+ * Pure functions: no filesystem, no clock dependency beyond the explicit
+ * `at` argument to tzOffsetFor. Real assertions on stability, spread, and
+ * timezone correctness.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  hashFraction,
+  jitterOffset,
+  jitterFor,
+  tzOffsetFor,
+  DEFAULT_WINDOW_MS,
+} from "./jitter.mjs";
+
+// ---------------------------------------------------------------------------
+// hashFraction
+// ---------------------------------------------------------------------------
+
+test("hashFraction returns a stable fraction in [0,1)", () => {
+  const a = hashFraction("alex morning-brief");
+  const b = hashFraction("alex morning-brief");
+  assert.equal(a, b, "same key must hash to the same fraction");
+  assert.ok(a >= 0 && a < 1, `fraction out of range: ${a}`);
+});
+
+test("hashFraction is roughly uniform across many keys", () => {
+  // 10 buckets; 2000 keys; every bucket should get a non-trivial share.
+  const buckets = new Array(10).fill(0);
+  for (let i = 0; i < 2000; i++) {
+    const f = hashFraction(`agent-${i}`);
+    buckets[Math.floor(f * 10)]++;
+  }
+  for (const count of buckets) {
+    assert.ok(count > 100, `bucket too sparse (${count}/2000) — not uniform`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// jitterOffset / jitterFor — stability
+// ---------------------------------------------------------------------------
+
+test("jitterFor is stable per (agent,cadence)", () => {
+  const base = 1_700_000_000_000;
+  const first = jitterFor("robin", "daily-digest", base, DEFAULT_WINDOW_MS);
+  const again = jitterFor("robin", "daily-digest", base, DEFAULT_WINDOW_MS);
+  assert.equal(first, again, "jitter must be deterministic for an agent");
+  // Different cadence → (almost surely) different slot.
+  const other = jitterFor("robin", "weekly-memo", base, DEFAULT_WINDOW_MS);
+  assert.notEqual(first, other);
+});
+
+test("jitterOffset stays strictly within [0, windowMs)", () => {
+  const windowMs = 300_000;
+  for (let i = 0; i < 500; i++) {
+    const off = jitterOffset(`agent-${i}`, "morning-brief", windowMs);
+    assert.ok(off >= 0 && off < windowMs, `offset ${off} out of window`);
+    assert.ok(Number.isInteger(off), "offset must be integer ms");
+  }
+});
+
+test("jitterFor adds the offset to the base time", () => {
+  const base = 1_700_000_000_000;
+  const off = jitterOffset("alex", "inbox", DEFAULT_WINDOW_MS);
+  assert.equal(jitterFor("alex", "inbox", base, DEFAULT_WINDOW_MS), base + off);
+});
+
+test("zero or invalid window yields zero offset (no jitter)", () => {
+  assert.equal(jitterOffset("alex", "c", 0), 0);
+  assert.equal(jitterOffset("alex", "c", -5), 0);
+  assert.equal(jitterOffset("alex", "c", NaN), 0);
+  // jitterFor with a bad base falls back to base 0.
+  assert.equal(jitterFor("alex", "c", NaN, 0), 0);
+});
+
+// ---------------------------------------------------------------------------
+// Fleet spread — the thundering-herd fix
+// ---------------------------------------------------------------------------
+
+test("a 60-agent fleet spreads across the window without clumping", () => {
+  const windowMs = 5 * 60 * 1000; // 5 minutes
+  const cadence = "morning-brief";
+  const offsets = [];
+  for (let i = 0; i < 60; i++) {
+    offsets.push(jitterOffset(`agent-${String(i).padStart(2, "0")}`, cadence, windowMs));
+  }
+  // All within the window.
+  for (const o of offsets) assert.ok(o >= 0 && o < windowMs);
+
+  // Spread: the offsets should cover a wide span, not collapse to one instant.
+  const min = Math.min(...offsets);
+  const max = Math.max(...offsets);
+  assert.ok(max - min > windowMs * 0.7, `spread too narrow: ${max - min}ms of ${windowMs}ms`);
+
+  // No thundering herd: with a 5-min window, no single 10s slot holds more
+  // than a small fraction of the fleet.
+  const slotMs = 10_000;
+  const slotCounts = new Map();
+  for (const o of offsets) {
+    const slot = Math.floor(o / slotMs);
+    slotCounts.set(slot, (slotCounts.get(slot) || 0) + 1);
+  }
+  const maxPerSlot = Math.max(...slotCounts.values());
+  assert.ok(maxPerSlot <= 8, `too many agents (${maxPerSlot}) in one 10s slot`);
+});
+
+// ---------------------------------------------------------------------------
+// tzOffsetFor
+// ---------------------------------------------------------------------------
+
+test("tzOffsetFor returns correct fixed-offset zones", () => {
+  // UTC is always 0.
+  assert.equal(tzOffsetFor("UTC", Date.UTC(2026, 0, 15, 12, 0, 0)), 0);
+  // Asia/Dubai is a fixed +4 (no DST) → +240 minutes.
+  assert.equal(tzOffsetFor("Asia/Dubai", Date.UTC(2026, 0, 15, 12, 0, 0)), 240);
+  // Asia/Kolkata is +5:30 → +330 minutes.
+  assert.equal(tzOffsetFor("Asia/Kolkata", Date.UTC(2026, 0, 15, 12, 0, 0)), 330);
+});
+
+test("tzOffsetFor is DST-aware for America/New_York", () => {
+  // Mid-January: EST = UTC-5 → -300.
+  assert.equal(tzOffsetFor("America/New_York", Date.UTC(2026, 0, 15, 17, 0, 0)), -300);
+  // Mid-July: EDT = UTC-4 → -240.
+  assert.equal(tzOffsetFor("America/New_York", Date.UTC(2026, 6, 15, 17, 0, 0)), -240);
+});
+
+test("tzOffsetFor fails open to 0 for an invalid timezone", () => {
+  assert.equal(tzOffsetFor("Not/AZone", Date.UTC(2026, 0, 1)), 0);
+  assert.equal(tzOffsetFor("", Date.UTC(2026, 0, 1)), 0);
+  assert.equal(tzOffsetFor(null, Date.UTC(2026, 0, 1)), 0);
+});
+
+test("tzOffsetFor accepts a Date or a ms epoch", () => {
+  const ms = Date.UTC(2026, 0, 15, 12, 0, 0);
+  assert.equal(tzOffsetFor("Asia/Dubai", new Date(ms)), tzOffsetFor("Asia/Dubai", ms));
+});