@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/util/fetch-timeout.test.mjs

@@ -1,202 +0,0 @@
-/**
- * lib/util/fetch-timeout.test.mjs
- *
- * node:test coverage for fetchWithTimeout:
- *  - a fast request passes through and returns the Response
- *  - a slow request aborts after the timeout with a typed FetchTimeoutError
- *  - a caller-supplied AbortSignal abort surfaces as the caller's error, not a
- *    timeout, and the timer is cleared
- *  - timeoutMs <= 0 disables the timeout (pass-through, no internal signal)
- *  - init is forwarded; the internal abort signal is injected
- *
- * Run: cd /Users/layla/maestro && node --test lib/util/fetch-timeout.test.mjs
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  fetchWithTimeout,
-  FetchTimeoutError,
-  DEFAULT_TIMEOUT_MS,
-} from "./fetch-timeout.mjs";
-
-/**
- * A fetch stub that resolves after `delayMs`, but rejects with an AbortError if
- * the provided signal aborts first — mirroring real `fetch` abort semantics.
- *
- * @param {number} delayMs
- * @param {*} [response]
- */
-function slowFetch(delayMs, response = { ok: true, status: 200 }) {
-  return (url, init) =>
-    new Promise((resolve, reject) => {
-      const signal = init && init.signal;
-      const t = setTimeout(() => resolve(response), delayMs);
-      if (signal) {
-        if (signal.aborted) {
-          clearTimeout(t);
-          const e = new Error("aborted");
-          e.name = "AbortError";
-          reject(e);
-          return;
-        }
-        signal.addEventListener(
-          "abort",
-          () => {
-            clearTimeout(t);
-            const e = new Error("aborted");
-            e.name = "AbortError";
-            reject(e);
-          },
-          { once: true }
-        );
-      }
-    });
-}
-
-/* ------------------------------- pass-through ----------------------------- */
-
-test("fast request passes through and returns the response", async () => {
-  const resp = { ok: true, status: 200, body: "hi" };
-  const out = await fetchWithTimeout("https://x/", {}, 1000, {
-    fetchImpl: slowFetch(0, resp),
-  });
-  assert.equal(out, resp);
-});
-
-test("init is forwarded and an abort signal is injected", async () => {
-  let seenInit = null;
-  const fetchImpl = (url, init) => {
-    seenInit = init;
-    return Promise.resolve({ ok: true });
-  };
-  await fetchWithTimeout(
-    "https://x/",
-    { method: "POST", headers: { "x-test": "1" } },
-    1000,
-    { fetchImpl }
-  );
-  assert.equal(seenInit.method, "POST");
-  assert.equal(seenInit.headers["x-test"], "1");
-  assert.ok(seenInit.signal, "internal AbortSignal should be injected into init");
-  assert.equal(seenInit.signal.aborted, false);
-});
-
-/* --------------------------------- timeout -------------------------------- */
-
-test("slow request aborts after the timeout with a typed error", async () => {
-  await assert.rejects(
-    () =>
-      fetchWithTimeout("https://slow/", {}, 20, {
-        fetchImpl: slowFetch(10_000),
-      }),
-    (err) => {
-      assert.ok(err instanceof FetchTimeoutError, `wrong type: ${err && err.name}`);
-      assert.equal(err.name, "FetchTimeoutError");
-      assert.equal(err.code, "ETIMEDOUT");
-      assert.equal(err.timeoutMs, 20);
-      assert.ok(String(err.message).includes("timed out"), err.message);
-      assert.ok(String(err.message).includes("slow"), "url should appear in message");
-      return true;
-    }
-  );
-});
-
-/* --------------------------- caller abort vs timeout ---------------------- */
-
-test("caller-supplied abort surfaces as the caller error, not a timeout", async () => {
-  const ac = new AbortController();
-  // Abort well before the (long) timeout would fire.
-  setTimeout(() => ac.abort(new Error("caller-cancelled")), 5);
-
-  await assert.rejects(
-    () =>
-      fetchWithTimeout("https://x/", { signal: ac.signal }, 10_000, {
-        fetchImpl: slowFetch(10_000),
-      }),
-    (err) => {
-      assert.ok(!(err instanceof FetchTimeoutError), "must not be a timeout error");
-      assert.notEqual(err.code, "ETIMEDOUT");
-      return true;
-    }
-  );
-});
-
-test("an already-aborted caller signal aborts immediately", async () => {
-  const ac = new AbortController();
-  ac.abort(new Error("pre-aborted"));
-  await assert.rejects(
-    () =>
-      fetchWithTimeout("https://x/", { signal: ac.signal }, 10_000, {
-        fetchImpl: slowFetch(10_000),
-      }),
-    (err) => {
-      assert.ok(!(err instanceof FetchTimeoutError));
-      return true;
-    }
-  );
-});
-
-/* ------------------------------ disabled timeout -------------------------- */
-
-test("non-positive timeout disables timing out (plain pass-through)", async () => {
-  let seenInit = null;
-  const fetchImpl = (url, init) => {
-    seenInit = init;
-    return Promise.resolve({ ok: true });
-  };
-  const out = await fetchWithTimeout("https://x/", { method: "GET" }, 0, {
-    fetchImpl,
-  });
-  assert.equal(out.ok, true);
-  // Pass-through leaves init untouched (no injected signal).
-  assert.equal(seenInit.method, "GET");
-  assert.equal(seenInit.signal, undefined);
-});
-
-/* -------------------------------- exports --------------------------------- */
-
-test("exposes a sane default timeout constant", () => {
-  assert.equal(typeof DEFAULT_TIMEOUT_MS, "number");
-  assert.ok(DEFAULT_TIMEOUT_MS > 0);
-});
-
-test("a non-function fetchImpl falls back to the global fetch", async () => {
-  // resolveFetch ignores a non-function fetchImpl and uses the global. We stub
-  // the global so this is deterministic and never hits the network.
-  const original = globalThis.fetch;
-  let used = false;
-  globalThis.fetch = () => {
-    used = true;
-    return Promise.resolve({ ok: true });
-  };
-  try {
-    const out = await fetchWithTimeout("https://x/", {}, 1000, { fetchImpl: 123 });
-    assert.equal(out.ok, true);
-    assert.equal(used, true);
-  } finally {
-    globalThis.fetch = original;
-  }
-});
-
-test("throws a clear error when no fetch implementation is available", async () => {
-  const original = globalThis.fetch;
-  // Remove the global so neither an injected nor a global fetch exists.
-  delete globalThis.fetch;
-  try {
-    await assert.rejects(
-      () => fetchWithTimeout("https://x/", {}, 1000),
-      (err) => {
-        assert.ok(err instanceof TypeError, `expected TypeError, got ${err && err.name}`);
-        assert.ok(
-          String(err.message).includes("no fetch implementation"),
-          err.message
-        );
-        return true;
-      }
-    );
-  } finally {
-    globalThis.fetch = original;
-  }
-});

package/lib/util/reconnect.test.mjs

@@ -1,369 +0,0 @@
-/**
- * lib/util/reconnect.test.mjs
- *
- * node:test coverage for the bounded-backoff reconnect supervisor. Everything is
- * driven by an injected fake clock + timer queue + RNG, so there are no real
- * sockets and no real time — the backoff-and-recover lifecycle is asserted
- * deterministically.
- *
- * Covered:
- *  - first connect surfaces connecting → up
- *  - a drop (notifyDown) drives down → connecting → up, recovering the connection
- *  - backoff grows decorrelated-jittered between attempts and is bounded by max
- *  - the attempt budget is honoured: exhausting it surfaces giving-up (never silent)
- *  - a failing connect() is treated as a drop and retried
- *  - isHealthy polling trips a reconnect when it returns false / throws
- *  - notifyDown is idempotent while a reconnect is already in flight
- *  - stop() cancels pending backoff + health poll and prevents further reconnects
- *  - decorrelatedBackoff bounds with an injected rng
- *  - a throwing onState sink can't crash the supervisor
- *
- * Run: cd /Users/layla/maestro && node --test lib/util/reconnect.test.mjs
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  superviseConnection,
-  decorrelatedBackoff,
-  CONN_STATE,
-  DEFAULT_BASE_BACKOFF_MS,
-  DEFAULT_MAX_BACKOFF_MS,
-} from "./reconnect.mjs";
-
-/**
- * A deterministic timer harness: setTimeout enqueues a callback with its delay;
- * `tick()` fires the earliest-due timer (advancing a logical clock), and
- * `flush()` runs everything queued. Returns the injectables to pass as cfg.
- */
-function fakeTimers() {
-  let nowMs = 0;
-  let seq = 0;
-  const timers = new Map(); // id -> { at, fn }
-  const api = {
-    now: () => nowMs,
-    setTimeout(fn, ms) {
-      const id = ++seq;
-      timers.set(id, { at: nowMs + Math.max(0, Number(ms) || 0), fn });
-      return { id, unref() { return this; } };
-    },
-    clearTimeout(handle) {
-      if (handle && timers.has(handle.id)) timers.delete(handle.id);
-    },
-    /** Fire the single earliest-due timer; advances the clock to its `at`. */
-    async tick() {
-      let next = null;
-      for (const [id, t] of timers) {
-        if (!next || t.at < next.t.at) next = { id, t };
-      }
-      if (!next) return false;
-      timers.delete(next.id);
-      nowMs = next.t.at;
-      // The fn may return a promise (the async connect attempt); await it so a
-      // failed attempt's freshly-armed backoff timer is visible to the next loop.
-      await next.t.fn();
-      // Yield a microtask turn so any .then/.catch scheduled by the connect
-      // settles before we pick the next timer.
-      await Promise.resolve();
-      return true;
-    },
-    /** Drain all currently-pending timers (and any they enqueue), to a cap. */
-    async flush(maxIters = 1000) {
-      let n = 0;
-      // Let any already-in-flight async attempt arm its first timer before we
-      // start draining.
-      await Promise.resolve();
-      while (timers.size && n < maxIters) {
-        await api.tick();
-        n++;
-      }
-    },
-    pending() { return timers.size; },
-  };
-  return api;
-}
-
-/** A connect() that resolves/rejects on demand, recording call order. */
-function scriptedConnect(plan) {
-  let i = 0;
-  const calls = [];
-  const connect = async () => {
-    const step = plan[Math.min(i, plan.length - 1)];
-    calls.push(step);
-    i++;
-    if (step && step.fail) throw new Error(step.error || "connect failed");
-    return step && step.handle !== undefined ? step.handle : `conn-${i}`;
-  };
-  connect.calls = calls;
-  connect.count = () => i;
-  return connect;
-}
-
-/** Collect onState transitions for assertions. */
-function recorder() {
-  const states = [];
-  const fn = (state, info) => states.push({ state, info });
-  fn.states = states;
-  fn.names = () => states.map((s) => s.state);
-  return fn;
-}
-
-test("first connect surfaces connecting → up and exposes the connection", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "socket-A" }]);
-  const sup = superviseConnection({ connect, onState, ...T });
-  await sup.started;
-  assert.deepEqual(onState.names(), [CONN_STATE.CONNECTING, CONN_STATE.UP]);
-  assert.equal(sup.state, CONN_STATE.UP);
-  assert.equal(sup.connection, "socket-A");
-  const up = onState.states.find((s) => s.state === CONN_STATE.UP);
-  assert.equal(up.info.reconnected, false);
-});
-
-test("a drop reconnects: down → connecting(backoff) → up, connection recovered", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "first" }, { handle: "second" }]);
-  const sup = superviseConnection({
-    connect,
-    onState,
-    rng: () => 0, // pin jitter to the floor for a predictable delay
-    baseBackoffMs: 100,
-    ...T,
-  });
-  await sup.started;
-  assert.equal(sup.state, CONN_STATE.UP);
-
-  // The owner observes a socket close.
-  sup.notifyDown("socket-closed");
-  assert.equal(sup.state, CONN_STATE.DOWN);
-  assert.equal(connect.count(), 1, "should not reconnect until the backoff fires");
-
-  // Fire the backoff timer → reconnect attempt → up again.
-  await T.flush();
-  assert.equal(sup.state, CONN_STATE.UP);
-  assert.equal(sup.connection, "second");
-  assert.equal(connect.count(), 2);
-
-  const names = onState.names();
-  // The reconnected "up" carries reconnected:true.
-  const lastUp = onState.states.filter((s) => s.state === CONN_STATE.UP).at(-1);
-  assert.equal(lastUp.info.reconnected, true);
-  assert.ok(names.includes(CONN_STATE.DOWN));
-  // The failure budget reset after recovery.
-  assert.equal(sup.attempts, 0);
-});
-
-test("backoff grows between attempts and is bounded by maxBackoffMs", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  // Always fail so we can watch successive backoff windows grow.
-  const connect = scriptedConnect([{ fail: true }]);
-  const sup = superviseConnection({
-    connect,
-    onState,
-    rng: () => 0.999999, // pin jitter to the TOP of each range
-    baseBackoffMs: 100,
-    maxBackoffMs: 1000,
-    backoffFactor: 3,
-    maxAttempts: 10,
-    ...T,
-  });
-  await sup.started; // first (failing) attempt completes and arms the first backoff
-  // Drive a handful of attempts and collect the scheduled backoff delays.
-  await T.flush(20);
-
-  // While a backoff timer is pending the connection is DOWN, and that event
-  // carries delayMs (the window until the next attempt).
-  const delays = onState.states
-    .filter((s) => s.state === CONN_STATE.DOWN && typeof s.info.delayMs === "number")
-    .map((s) => s.info.delayMs);
-
-  assert.ok(delays.length >= 3, `expected several backoff windows, got ${delays.length}`);
-  // Decorrelated growth with rng pinned to the top of each range:
-  //   prev=0   → [100,100] → 100
-  //   prev=100 → [100,300] → ~300
-  //   prev=300 → [100,900] → ~900
-  //   prev=900 → [100,2700] capped at 1000
-  assert.ok(delays[1] >= delays[0], `windows should trend upward: ${delays.slice(0, 3)}`);
-  // Every window respects the ceiling.
-  for (const d of delays) assert.ok(d <= 1000, `window ${d} exceeded max`);
-  // And none drops below the floor.
-  for (const d of delays) assert.ok(d >= 100, `window ${d} below base`);
-});
-
-test("exhausting the attempt budget surfaces giving-up (never silent)", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ fail: true }]); // always fails
-  const sup = superviseConnection({
-    connect,
-    onState,
-    maxAttempts: 3,
-    baseBackoffMs: 10,
-    rng: () => 0,
-    ...T,
-  });
-  await sup.started; // first failing attempt completes and arms the first backoff
-  await T.flush();
-  assert.equal(sup.state, CONN_STATE.GIVING_UP, "must reach the terminal state, not die silently");
-  const giveUp = onState.states.find((s) => s.state === CONN_STATE.GIVING_UP);
-  assert.ok(giveUp, "a giving-up transition must be emitted");
-  assert.equal(giveUp.info.attempts, 3);
-  // No more reconnects after giving up.
-  const before = connect.count();
-  sup.notifyDown("late drop");
-  await T.flush();
-  assert.equal(connect.count(), before, "no reconnect attempts after giving-up");
-});
-
-test("a failing connect is treated as a drop and retried until it succeeds", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  // Fail twice, then succeed.
-  const connect = scriptedConnect([{ fail: true }, { fail: true }, { handle: "live" }]);
-  const sup = superviseConnection({
-    connect,
-    onState,
-    maxAttempts: 5,
-    baseBackoffMs: 10,
-    rng: () => 0,
-    ...T,
-  });
-  await sup.started; // first failing attempt completes and arms the first backoff
-  await T.flush();
-  assert.equal(sup.state, CONN_STATE.UP);
-  assert.equal(sup.connection, "live");
-  assert.equal(connect.count(), 3);
-});
-
-test("isHealthy polling trips a reconnect when it returns false", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "a" }, { handle: "b" }]);
-  let healthy = true;
-  const sup = superviseConnection({
-    connect,
-    onState,
-    isHealthy: () => healthy,
-    healthIntervalMs: 1000,
-    baseBackoffMs: 10,
-    rng: () => 0,
-    ...T,
-  });
-  await sup.started;
-  assert.equal(sup.state, CONN_STATE.UP);
-
-  // Mark the connection unhealthy; the next poll should see it and reconnect.
-  healthy = false;
-  await T.tick(); // fire the health poll → reportDown
-  // After the poll trips, make subsequent connects healthy again.
-  healthy = true;
-  await T.flush(); // backoff + reconnect + re-arm poll
-  assert.equal(sup.state, CONN_STATE.UP);
-  assert.equal(connect.count(), 2, "reconnected after a failed health poll");
-});
-
-test("a throwing isHealthy counts as unhealthy and reconnects", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "a" }, { handle: "b" }]);
-  let mode = "ok";
-  const sup = superviseConnection({
-    connect,
-    onState,
-    isHealthy: () => {
-      if (mode === "throw") throw new Error("health probe blew up");
-      return true;
-    },
-    healthIntervalMs: 1000,
-    baseBackoffMs: 10,
-    rng: () => 0,
-    ...T,
-  });
-  await sup.started;
-  mode = "throw";
-  await T.tick(); // health poll throws → treated as down
-  mode = "ok";
-  await T.flush();
-  assert.equal(sup.state, CONN_STATE.UP);
-  assert.equal(connect.count(), 2);
-});
-
-test("notifyDown is idempotent while a reconnect is already in flight", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "a" }, { handle: "b" }]);
-  const sup = superviseConnection({ connect, onState, baseBackoffMs: 50, rng: () => 0, ...T });
-  await sup.started;
-
-  // Several rapid close events should collapse into ONE reconnect cycle.
-  sup.notifyDown("close-1");
-  sup.notifyDown("close-2");
-  sup.notifyDown("close-3");
-  assert.equal(T.pending(), 1, "only one backoff timer should be armed");
-  await T.flush();
-  assert.equal(connect.count(), 2, "exactly one reconnect, not three");
-});
-
-test("stop() cancels pending backoff + health poll and blocks further reconnects", async () => {
-  const T = fakeTimers();
-  const onState = recorder();
-  const connect = scriptedConnect([{ handle: "a" }]);
-  const sup = superviseConnection({
-    connect,
-    onState,
-    isHealthy: () => true,
-    healthIntervalMs: 1000,
-    baseBackoffMs: 50,
-    rng: () => 0,
-    ...T,
-  });
-  await sup.started;
-  assert.ok(T.pending() >= 1, "health poll timer should be armed while up");
-
-  sup.notifyDown("drop"); // arms a backoff timer
-  sup.stop("shutting down");
-  assert.equal(T.pending(), 0, "stop() must clear all pending timers");
-
-  const before = connect.count();
-  sup.notifyDown("late drop");
-  await T.flush();
-  assert.equal(connect.count(), before, "no reconnect after stop()");
-});
-
-test("a throwing onState sink cannot crash the supervisor", async () => {
-  const T = fakeTimers();
-  const connect = scriptedConnect([{ handle: "a" }]);
-  const sup = superviseConnection({
-    connect,
-    onState: () => { throw new Error("bad sink"); },
-    ...T,
-  });
-  await assert.doesNotReject(() => sup.started);
-  assert.equal(sup.state, CONN_STATE.UP);
-});
-
-test("decorrelatedBackoff bounds the window with an injected rng", () => {
-  // rng=0 → floor; rng→1 → top of [base, prev*factor] capped at max.
-  assert.equal(decorrelatedBackoff(0, { base: 100, max: 5000, factor: 3, rng: () => 0 }), 100);
-  const top = decorrelatedBackoff(100, { base: 100, max: 5000, factor: 3, rng: () => 0.999999 });
-  assert.ok(top <= 300 && top >= 100, `expected within [100,300], got ${top}`);
-  // The cap holds even with a large prev.
-  assert.equal(
-    decorrelatedBackoff(100000, { base: 100, max: 1000, factor: 3, rng: () => 0.999999 }),
-    1000
-  );
-});
-
-test("exposes sane default backoff constants", () => {
-  assert.equal(typeof DEFAULT_BASE_BACKOFF_MS, "number");
-  assert.equal(typeof DEFAULT_MAX_BACKOFF_MS, "number");
-  assert.ok(DEFAULT_MAX_BACKOFF_MS > DEFAULT_BASE_BACKOFF_MS);
-});
-
-test("superviseConnection requires a connect function", () => {
-  assert.throws(() => superviseConnection({}), /connect must be a function/);
-});