@cohortapp/agent-sdk 2.17.0 → 2.18.4

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

@@ -1,344 +0,0 @@
-/**
- * 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

@@ -1,140 +0,0 @@
-/**
- * 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));
-});