@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/rate-guard.test.mjs

@@ -1,272 +0,0 @@
-/**
- * rate-guard.test.mjs — node:test coverage for the shared 429 breaker.
- *
- * Everything is hermetic: the state dir is an isolated tmpdir per test, and
- * the clock + rng are injected so backoff windows are deterministic.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { promises as fsp } from "node:fs";
-import { existsSync, readFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  checkRateLimit,
-  recordRateLimit,
-  recordSuccess,
-  decorrelatedBackoff,
-  classifyStderr,
-  classifyUsageLimit,
-  parseResetAt,
-  recordUsageLimit,
-  readState,
-  sanitizeProvider,
-  RATE_BASE_BACKOFF_MS,
-  RATE_MAX_BACKOFF_MS,
-  RATE_BACKOFF_FACTOR,
-  RATE_USAGE_LIMIT_HOLD_MS,
-} from "./rate-guard.mjs";
-
-async function makeStateDir() {
-  const path = join(tmpdir(), `rate-guard-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-  await fsp.mkdir(path, { recursive: true });
-  return path;
-}
-async function rm(path) { try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ } }
-
-// Fixed-clock helper.
-function fixedClock(t) { return () => t; }
-
-// ---------------------------------------------------------------------------
-// classifyStderr
-// ---------------------------------------------------------------------------
-
-test("classifyStderr matches 429 / rate limit / overloaded variants", () => {
-  assert.equal(classifyStderr("HTTP 429 Too Many Requests"), true);
-  assert.equal(classifyStderr("Error: rate limit exceeded"), true);
-  assert.equal(classifyStderr("rate-limit hit"), true);
-  assert.equal(classifyStderr("the model is Overloaded right now"), true);
-  assert.equal(classifyStderr("too many requests, slow down"), true);
-  // Negatives
-  assert.equal(classifyStderr("connection refused"), false);
-  assert.equal(classifyStderr("permission denied"), false);
-  assert.equal(classifyStderr(""), false);
-  assert.equal(classifyStderr(null), false);
-  // 429 must be a word boundary, not part of a longer number
-  assert.equal(classifyStderr("error code 14290 unrelated"), false);
-});
-
-// ---------------------------------------------------------------------------
-// breaker open/close
-// ---------------------------------------------------------------------------
-
-test("breaker starts closed (allows) when no state file exists", async () => {
-  const dir = await makeStateDir();
-  try {
-    const r = checkRateLimit("anthropic", { stateDir: dir });
-    assert.equal(r.allowed, true);
-    assert.equal(r.retryAt, null);
-  } finally { await rm(dir); }
-});
-
-test("recordRateLimit opens the breaker so the next check is gated", async () => {
-  const dir = await makeStateDir();
-  try {
-    const t0 = 1_000_000;
-    // Deterministic rng → pick the high end of the range.
-    const rec = recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.999999 });
-    assert.ok(rec.backoffMs >= RATE_BASE_BACKOFF_MS);
-    assert.equal(rec.openUntil, t0 + rec.backoffMs);
-    assert.equal(rec.consecutive429, 1);
-
-    // A check WHILE the window is open is gated.
-    const mid = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 10) });
-    assert.equal(mid.allowed, false);
-    assert.equal(mid.retryAt, rec.openUntil);
-
-    // A check AFTER the window closes is allowed again.
-    const after = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(rec.openUntil + 1) });
-    assert.equal(after.allowed, true);
-  } finally { await rm(dir); }
-});
-
-test("recordSuccess closes the breaker and resets backoff", async () => {
-  const dir = await makeStateDir();
-  try {
-    const t0 = 5_000_000;
-    recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.5 });
-    // While open, gated.
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 5) }).allowed, false);
-    // Success clears it.
-    recordSuccess("anthropic", { stateDir: dir, now: fixedClock(t0 + 6) });
-    const s = readState("anthropic", { stateDir: dir });
-    assert.equal(s.openUntil, 0);
-    assert.equal(s.consecutive429, 0);
-    assert.equal(s.lastBackoffMs, 0);
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 7) }).allowed, true);
-  } finally { await rm(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// decorrelated backoff bounds
-// ---------------------------------------------------------------------------
-
-test("decorrelatedBackoff stays within [base, prev*factor] and respects rng extremes", () => {
-  // First hit (prev=0): range collapses to [base, base].
-  assert.equal(decorrelatedBackoff(0, { rng: () => 0 }), RATE_BASE_BACKOFF_MS);
-  assert.equal(decorrelatedBackoff(0, { rng: () => 0.999999 }), RATE_BASE_BACKOFF_MS);
-
-  // Subsequent hit: prev=10s, factor default 3 → range [base, 30s].
-  const prev = 10_000;
-  const lo = decorrelatedBackoff(prev, { rng: () => 0 });
-  const hi = decorrelatedBackoff(prev, { rng: () => 0.999999 });
-  assert.equal(lo, RATE_BASE_BACKOFF_MS);
-  assert.ok(hi <= prev * RATE_BACKOFF_FACTOR);
-  assert.ok(hi >= lo);
-  // A mid pick lands strictly inside the range.
-  const mid = decorrelatedBackoff(prev, { rng: () => 0.5 });
-  assert.ok(mid > lo && mid < hi, `mid ${mid} should be inside (${lo}, ${hi})`);
-});
-
-test("decorrelatedBackoff caps at RATE_MAX_BACKOFF_MS", () => {
-  // Huge prev would blow past 15min; the cap clamps it.
-  const capped = decorrelatedBackoff(RATE_MAX_BACKOFF_MS * 100, { rng: () => 0.999999 });
-  assert.equal(capped, RATE_MAX_BACKOFF_MS);
-});
-
-test("consecutive hits grow the backoff window (decorrelated escalation)", async () => {
-  const dir = await makeStateDir();
-  try {
-    let t = 0;
-    // Always pick the top of the range so growth is monotonic and assertable.
-    const deps = { stateDir: dir, now: () => t, rng: () => 0.999999 };
-    const w1 = recordRateLimit("anthropic", deps).backoffMs;
-    t += w1 + 1;
-    const w2 = recordRateLimit("anthropic", deps).backoffMs;
-    t += w2 + 1;
-    const w3 = recordRateLimit("anthropic", deps).backoffMs;
-    assert.ok(w2 >= w1, `w2 ${w2} should be >= w1 ${w1}`);
-    assert.ok(w3 >= w2, `w3 ${w3} should be >= w2 ${w2}`);
-    assert.equal(readState("anthropic", { stateDir: dir }).consecutive429, 3);
-  } finally { await rm(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// shared file — one breaker for all sources
-// ---------------------------------------------------------------------------
-
-test("the breaker is a single shared file: one source opens it, another sees it", async () => {
-  const dir = await makeStateDir();
-  try {
-    const t0 = 9_000_000;
-    // "dispatcher" records the hit…
-    const rec = recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.7 });
-    // …and the "cadence-consumer" (separate caller, same provider+dir) is gated.
-    const consumerView = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 1) });
-    assert.equal(consumerView.allowed, false);
-    assert.equal(consumerView.retryAt, rec.openUntil);
-    // The file physically exists on disk under the shared dir.
-    assert.ok(existsSync(join(dir, "anthropic.json")));
-    const persisted = JSON.parse(readFileSync(join(dir, "anthropic.json"), "utf-8"));
-    assert.equal(persisted.openUntil, rec.openUntil);
-  } finally { await rm(dir); }
-});
-
-test("different providers have independent breakers", async () => {
-  const dir = await makeStateDir();
-  try {
-    const t0 = 2_000_000;
-    recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.9 });
-    // moonshot is untouched → still allowed.
-    assert.equal(checkRateLimit("moonshot", { stateDir: dir, now: fixedClock(t0 + 1) }).allowed, true);
-    // anthropic is gated.
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 1) }).allowed, false);
-  } finally { await rm(dir); }
-});
-
-test("sanitizeProvider keeps keys filesystem-safe", () => {
-  assert.equal(sanitizeProvider("Anthropic"), "anthropic");
-  assert.equal(sanitizeProvider("open/router"), "open-router");
-  assert.equal(sanitizeProvider(""), "anthropic");
-  assert.equal(sanitizeProvider(undefined), "anthropic");
-});
-
-test("readState tolerates a corrupt file (fails closed-to-empty, never throws)", async () => {
-  const dir = await makeStateDir();
-  try {
-    await fsp.writeFile(join(dir, "anthropic.json"), "{ not json");
-    const s = readState("anthropic", { stateDir: dir });
-    assert.deepEqual(s, { openUntil: 0, consecutive429: 0, lastBackoffMs: 0 });
-    // And a check on corrupt state allows work (fail-open-for-work).
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir }).allowed, true);
-  } finally { await rm(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// classifyUsageLimit / parseResetAt / recordUsageLimit  (Max session-limit)
-// ---------------------------------------------------------------------------
-
-test("classifyUsageLimit detects session/usage limits, not plain 429s", () => {
-  assert.equal(classifyUsageLimit("You've hit your session limit · resets 9:40pm (Australia/Sydney)").isLimit, true);
-  assert.equal(classifyUsageLimit("usage limit reached").isLimit, true);
-  assert.equal(classifyUsageLimit("You have reached your weekly limit").isLimit, true);
-  assert.equal(classifyUsageLimit("out of usage for now").isLimit, true);
-  // A plain transient 429 is NOT a usage-window limit
-  assert.equal(classifyUsageLimit("HTTP 429 Too Many Requests").isLimit, false);
-  assert.equal(classifyUsageLimit("overloaded").isLimit, false);
-  assert.equal(classifyUsageLimit("").isLimit, false);
-  assert.equal(classifyUsageLimit(null).isLimit, false);
-});
-
-test("parseResetAt resolves a stated reset time to the next occurrence", () => {
-  // now = 2026-08-26 08:00 local; "resets 9:40pm" is later today
-  const now = new Date(2026, 7, 26, 8, 0, 0, 0).getTime();
-  const t = parseResetAt("resets 9:40pm", { now: () => now });
-  const d = new Date(t);
-  assert.equal(d.getHours(), 21);
-  assert.equal(d.getMinutes(), 40);
-  assert.ok(t > now, "reset is in the future");
-  // A time already past today rolls to tomorrow
-  const now2 = new Date(2026, 7, 26, 22, 0, 0, 0).getTime(); // 10pm
-  const t2 = parseResetAt("try again at 9pm", { now: () => now2 });
-  assert.ok(t2 > now2 && t2 - now2 <= 24 * 60 * 60 * 1000, "rolls to next day");
-  assert.equal(parseResetAt("no time here", { now: () => now }), null);
-});
-
-test("recordUsageLimit holds the breaker until the parsed reset time", async () => {
-  const dir = await makeStateDir();
-  try {
-    const now = new Date(2026, 7, 26, 8, 0, 0, 0).getTime();
-    const { resetAt } = classifyUsageLimit("session limit · resets 9:40pm", { now: () => now });
-    const rec = recordUsageLimit("anthropic", resetAt, { stateDir: dir, now: () => now });
-    assert.equal(rec.openUntil, resetAt);
-    // blocked before reset, allowed after
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => now + 1000 }).allowed, false);
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => resetAt + 1 }).allowed, true);
-  } finally { await rm(dir); }
-});
-
-test("recordUsageLimit falls back to a default hold when no reset is known", async () => {
-  const dir = await makeStateDir();
-  try {
-    const now = 1_000_000;
-    const rec = recordUsageLimit("anthropic", null, { stateDir: dir, now: () => now });
-    assert.equal(rec.openUntil, now + RATE_USAGE_LIMIT_HOLD_MS);
-    assert.equal(rec.resetAt, null);
-    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => now + 1000 }).allowed, false);
-  } finally { await rm(dir); }
-});
-
-test("recordUsageLimit never shortens an already-longer open window", async () => {
-  const dir = await makeStateDir();
-  try {
-    const now = 1_000_000;
-    const far = now + 10 * 60 * 60 * 1000; // 10h out
-    recordUsageLimit("anthropic", far, { stateDir: dir, now: () => now });
-    // a later, SHORTER hold must not pull the window in
-    const rec = recordUsageLimit("anthropic", now + 5 * 60 * 1000, { stateDir: dir, now: () => now });
-    assert.equal(rec.openUntil, far);
-  } finally { await rm(dir); }
-});

package/lib/reactive-gate.test.mjs

@@ -1,57 +0,0 @@
-/**
- * reactive-gate — the process-local counter that tells the governor + dispatcher
- * a human/peer reply is actively consuming the subscription.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import {
-  markReactiveStart,
-  markReactiveEnd,
-  reactiveInFlight,
-  reactivePeak,
-  _resetReactiveGate,
-} from "./reactive-gate.mjs";
-
-test("starts at zero", () => {
-  _resetReactiveGate();
-  assert.equal(reactiveInFlight(), 0);
-});
-
-test("start/end move the count by exactly one and balance to zero", () => {
-  _resetReactiveGate();
-  assert.equal(markReactiveStart(), 1);
-  assert.equal(reactiveInFlight(), 1);
-  assert.equal(markReactiveEnd(), 0);
-  assert.equal(reactiveInFlight(), 0);
-});
-
-test("concurrent reactive turns NEST — backlog resumes only when the last ends", () => {
-  _resetReactiveGate();
-  markReactiveStart();
-  markReactiveStart();
-  assert.equal(reactiveInFlight(), 2, "two turns in flight");
-  markReactiveEnd();
-  assert.equal(reactiveInFlight(), 1, "still one waiting — do NOT resume backlog yet");
-  markReactiveEnd();
-  assert.equal(reactiveInFlight(), 0, "now backlog may resume");
-});
-
-test("end is clamped at zero — an unbalanced end can never wedge backlog off", () => {
-  _resetReactiveGate();
-  assert.equal(markReactiveEnd(), 0, "end with nothing in flight stays at 0");
-  assert.equal(markReactiveEnd(), 0, "and again");
-  // A subsequent real turn still registers correctly (not driven negative).
-  assert.equal(markReactiveStart(), 1);
-  assert.equal(reactiveInFlight(), 1);
-});
-
-test("peak records the high-water mark since reset", () => {
-  _resetReactiveGate();
-  markReactiveStart();
-  markReactiveStart();
-  markReactiveStart();
-  markReactiveEnd();
-  markReactiveEnd();
-  assert.equal(reactivePeak(), 3, "peak holds even after turns end");
-  assert.equal(reactiveInFlight(), 1);
-});

package/lib/render.test.mjs

@@ -1,68 +0,0 @@
-/**
- * render.test.mjs — tests for the {{agent.*}} template substitution engine.
- * Run: `node --test lib/render.test.mjs`
- * @module render.test
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  renderTemplate,
-  buildContext,
-  collectTokens,
-  unknownTokens,
-  KNOWN_TOKENS,
-} from "./render.mjs";
-
-const AGENT = {
-  firstName: "Jacob", fullName: "Jacob Chen", title: "VP, Engineering",
-  email: "jacob@acme.com", phone: "", company: "Acme",
-  principal: { firstName: "Dana", fullName: "Dana Reyes", title: "CEO", email: "dana@acme.com" },
-};
-const PROFILE = { label: "VP, Engineering", domain: "Engineering delivery" };
-const COMPANY = { name: "Acme Capital", website: "https://acme.com", industry: "Asset management", domain: "acme.com" };
-const CTX = buildContext(AGENT, PROFILE, COMPANY);
-
-test("renderTemplate resolves agent.*, archetype.*, and company.* dot-paths", () => {
-  assert.equal(renderTemplate("Hi, I'm {{agent.fullName}}, {{agent.title}}.", CTX), "Hi, I'm Jacob Chen, VP, Engineering.");
-  assert.equal(renderTemplate("Reports to {{agent.principal.fullName}} ({{agent.principal.title}}).", CTX), "Reports to Dana Reyes (CEO).");
-  assert.equal(renderTemplate("Domain: {{archetype.domain}}", CTX), "Domain: Engineering delivery");
-  assert.equal(renderTemplate("At {{company.name}} ({{company.industry}}) — {{company.website}}", CTX), "At Acme Capital (Asset management) — https://acme.com");
-});
-
-test("renderTemplate is a no-op on token-free text (fast path)", () => {
-  const s = "No tokens here at all.";
-  assert.equal(renderTemplate(s, CTX), s);
-  assert.equal(renderTemplate("", CTX), "");
-  assert.equal(renderTemplate(undefined, CTX), undefined);
-});
-
-test("renderTemplate leaves unresolved / unknown tokens verbatim (never silently empties)", () => {
-  assert.equal(renderTemplate("x {{agent.nope}} y", CTX), "x {{agent.nope}} y");
-  assert.equal(renderTemplate("x {{totally.bogus}} y", CTX), "x {{totally.bogus}} y");
-  // present-but-empty value (phone="") resolves to empty string, not left verbatim:
-  assert.equal(renderTemplate("p[{{agent.phone}}]", CTX), "p[]");
-});
-
-test("renderTemplate tolerates whitespace inside braces", () => {
-  assert.equal(renderTemplate("{{ agent.firstName }}", CTX), "Jacob");
-});
-
-test("collectTokens returns all token paths in order", () => {
-  assert.deepEqual(collectTokens("{{agent.fullName}} <{{agent.email}}>"), ["agent.fullName", "agent.email"]);
-  assert.deepEqual(collectTokens("none"), []);
-});
-
-test("unknownTokens flags only tokens outside the vocabulary", () => {
-  assert.deepEqual(unknownTokens("{{agent.fullName}} {{agent.principal.email}}"), []);
-  assert.deepEqual(unknownTokens("{{agent.firstname}} {{stray}}").sort(), ["agent.firstname", "stray"]);
-});
-
-test("KNOWN_TOKENS covers the documented identity vocabulary", () => {
-  for (const t of ["agent.firstName", "agent.fullName", "agent.title", "agent.email", "agent.company", "agent.principal.fullName", "archetype.label"]) {
-    assert.ok(KNOWN_TOKENS.has(t), `expected ${t} in KNOWN_TOKENS`);
-  }
-});