agent-yes 1.164.0 → 1.166.0

package/ts/spawnGate.spec.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import {
+  memAvailableMb,
+  spawnGateEnabled,
+  spawnRejectionReason,
+  waitForSpawnCapacity,
+} from "./spawnGate.ts";
+
+// Build a minimal live pid record. Using the test runner's own pid guarantees
+// `isProcessAlive` (process.kill(pid, 0)) succeeds, so the record counts as live.
+const liveRecord = (pid: number) =>
+  JSON.stringify({
+    pid,
+    cli: "claude",
+    prompt: null,
+    cwd: "/tmp",
+    log_file: null,
+    status: "active",
+    exit_code: null,
+    exit_reason: null,
+    started_at: 0,
+  });
+
+describe("spawnGate", () => {
+  let original: string | undefined;
+  let tmp: string;
+  const writePids = (lines: string[]) =>
+    writeFileSync(path.join(tmp, "pids.jsonl"), lines.join("\n") + "\n");
+
+  beforeEach(() => {
+    original = process.env.AGENT_YES_HOME;
+    tmp = mkdtempSync(path.join(tmpdir(), "ay-gate-"));
+    process.env.AGENT_YES_HOME = tmp;
+  });
+  afterEach(() => {
+    if (original === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = original;
+    delete process.env.AGENT_YES_MAX_AGENTS;
+    delete process.env.AGENT_YES_MIN_FREE_MB;
+    delete process.env.AGENT_YES_SPAWN_WAIT_MS;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  describe("memAvailableMb", () => {
+    it("returns a positive number on this host", async () => {
+      const mb = await memAvailableMb();
+      expect(mb).not.toBeNull();
+      expect(mb!).toBeGreaterThan(0);
+    });
+  });
+
+  describe("spawnGateEnabled", () => {
+    it("is false when nothing is configured", () => {
+      expect(spawnGateEnabled()).toBe(false);
+    });
+    it("is true when a cap or floor is set", () => {
+      process.env.AGENT_YES_MAX_AGENTS = "5";
+      expect(spawnGateEnabled()).toBe(true);
+    });
+  });
+
+  describe("spawnRejectionReason", () => {
+    it("returns null when no limits are configured", async () => {
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("rejects when live agents reach the cap", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+      expect(await spawnRejectionReason()).toMatch(/too many agents running \(1\/1\)/);
+    });
+
+    it("admits when live agents are under the cap", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "5";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("ignores dead pids when counting live agents", async () => {
+      // pid 2^31-1 is effectively never a live process → not counted.
+      writePids([liveRecord(2147483646)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("rejects when free memory is below the floor", async () => {
+      process.env.AGENT_YES_MIN_FREE_MB = String(Number.MAX_SAFE_INTEGER);
+      expect(await spawnRejectionReason()).toMatch(/host is low on memory/);
+    });
+
+    it("admits when free memory is above the floor", async () => {
+      process.env.AGENT_YES_MIN_FREE_MB = "1";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+  });
+
+  describe("waitForSpawnCapacity", () => {
+    it("returns immediately (no sleep) when the gate is disabled", async () => {
+      const sleeps: number[] = [];
+      await waitForSpawnCapacity({ sleep: async (ms) => void sleeps.push(ms) });
+      expect(sleeps).toEqual([]);
+    });
+
+    it("backs off with φ growth and fails open at the deadline", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1"; // always over → never admits
+
+      let t = 0;
+      const sleeps: number[] = [];
+      let proceededAfter: number | null = null;
+      await waitForSpawnCapacity({
+        maxWaitMs: 5000,
+        now: () => t,
+        sleep: async (ms) => {
+          sleeps.push(ms);
+          t += ms;
+        },
+        onProceedAnyway: (_r, waited) => {
+          proceededAfter = waited;
+        },
+      });
+
+      // 1000, then ×φ (1618), then clamped to the remaining 2382ms before deadline.
+      expect(sleeps[0]).toBe(1000);
+      expect(sleeps[1]).toBe(1618);
+      expect(sleeps.reduce((a, b) => a + b, 0)).toBe(5000);
+      expect(proceededAfter).toBe(5000);
+    });
+
+    it("admits as soon as capacity frees, without proceeding-anyway", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+
+      const sleeps: number[] = [];
+      let proceeded = false;
+      await waitForSpawnCapacity({
+        maxWaitMs: 600_000,
+        sleep: async (ms) => {
+          sleeps.push(ms);
+          // free up capacity after two backoff cycles
+          if (sleeps.length >= 2) process.env.AGENT_YES_MAX_AGENTS = "10";
+        },
+        onProceedAnyway: () => {
+          proceeded = true;
+        },
+      });
+
+      expect(sleeps.length).toBe(2);
+      expect(proceeded).toBe(false);
+    });
+  });
+});

package/ts/spawnGate.ts

@@ -0,0 +1,123 @@
+/**
+ * Spawn admission control — keep an unbounded fan-out of agents from exhausting
+ * host RAM and tripping the kernel OOM-killer (which, on a box with no cgroup
+ * memory limit, hangs the whole machine). Two opt-in limits:
+ *   - {@link getMaxAgents}  — max concurrently-live agents
+ *   - {@link getMinFreeMb}  — minimum free memory before admitting a spawn
+ *
+ * Two entry points share one instantaneous check ({@link spawnRejectionReason}):
+ *   - the `ay serve` daemon HARD-REJECTS (`/api/spawn` → 429) so the caller retries;
+ *   - the CLI path BLOCKS-AND-WAITS ({@link waitForSpawnCapacity}) with φ-backoff,
+ *     failing open after a timeout so recursive `ay <cli>` spawns get spaced out
+ *     (the actual cause of the burst storms) without ever deadlocking a workflow.
+ */
+import { readFile } from "fs/promises";
+import { readGlobalPids } from "./globalPidIndex.ts";
+import { getMaxAgents, getMinFreeMb, getSpawnWaitMs } from "./workspaceConfig.ts";
+
+/**
+ * System available memory in MB. Prefers Linux `/proc/meminfo` `MemAvailable`
+ * (the kernel's own estimate of what's reclaimable without swapping — far more
+ * accurate than free RAM), falling back to `os.freemem()` on other platforms or
+ * if the file can't be parsed. Returns null when nothing usable is available.
+ */
+export async function memAvailableMb(): Promise<number | null> {
+  try {
+    const txt = await readFile("/proc/meminfo", "utf-8");
+    const m = /^MemAvailable:\s+(\d+)\s*kB/m.exec(txt);
+    if (m) return Math.floor(Number(m[1]) / 1024);
+  } catch {
+    /* not Linux / unreadable — fall through */
+  }
+  try {
+    const { freemem } = await import("os");
+    return Math.floor(freemem() / (1024 * 1024));
+  } catch {
+    return null;
+  }
+}
+
+/** True when at least one spawn limit is configured (else the gate is a no-op). */
+export function spawnGateEnabled(): boolean {
+  return getMaxAgents() !== undefined || getMinFreeMb() !== undefined;
+}
+
+/**
+ * Instantaneous capacity check. Returns a human-readable reason string when a
+ * new spawn should be held back (cap reached / memory too low), or null when
+ * there's capacity. Both limits are opt-in — unset means no check.
+ *
+ * NOTE — the `maxAgents` count is BEST-EFFORT, not a hard barrier: the check is
+ * non-atomic (check here → register in `pids.jsonl` later, in another process),
+ * so a simultaneous burst can briefly overshoot the cap before the new wrappers
+ * appear in the live count. That's acceptable because (a) the CLI path's
+ * φ-backoff desynchronizes retries, spreading a burst out, and (b) `minFreeMb`
+ * is the HARD OOM guard — it's re-evaluated against live `/proc/meminfo` on every
+ * attempt, so once RAM actually drops, further spawns are held regardless of the
+ * count. Exact admission would need a cross-process reservation+lock (a TTL'd
+ * reservation file); deliberately deferred to avoid stale reservations wedging
+ * spawns, which would be worse than a transient overshoot.
+ */
+export async function spawnRejectionReason(): Promise<string | null> {
+  const maxAgents = getMaxAgents();
+  if (maxAgents !== undefined) {
+    // Live agents already running (this wrapper hasn't registered itself yet),
+    // so "live >= cap" admits exactly `maxAgents` concurrent agents.
+    const live = (await readGlobalPids({ liveOnly: true })).length;
+    if (live >= maxAgents)
+      // Phrased for the end user who clicked "Spawn" (the console shows this
+      // string verbatim), with a host-admin hint appended in parentheses.
+      return `too many agents running (${live}/${maxAgents}) — this agent wasn't started. Please wait for one to finish and try again. (host: raise "maxAgents" in ~/.agent-yes/config.json or AGENT_YES_MAX_AGENTS)`;
+  }
+  const minFreeMb = getMinFreeMb();
+  if (minFreeMb !== undefined) {
+    const avail = await memAvailableMb();
+    if (avail !== null && avail < minFreeMb)
+      return `the host is low on memory (${avail}MB free, needs ${minFreeMb}MB) — this agent wasn't started, to avoid crashing the machine. Please try again in a moment. (host: adjust "minFreeMb" in ~/.agent-yes/config.json or AGENT_YES_MIN_FREE_MB)`;
+  }
+  return null;
+}
+
+const PHI = 1.618; // golden-ratio backoff base (snomiao global pref)
+const BACKOFF_CAP_MS = 60_000;
+const BACKOFF_BASE_MS = 1_000;
+
+/**
+ * Block until there's spawn capacity, polling with φ-backoff (1s × φⁿ, capped at
+ * 60s — there is no OS event for "memory freed", so polling is unavoidable here).
+ * Fails open after {@link getSpawnWaitMs} ms (default 10 min): on timeout it logs
+ * and proceeds, so a set of mutually-waiting recursive spawns can never deadlock
+ * permanently. A no-op (returns immediately) when no limit is configured, so it
+ * adds ~zero overhead to the spawn hot path for users who haven't opted in.
+ *
+ * `sleep`/`now` are injectable for tests. `onWait` fires once per backoff cycle.
+ */
+export async function waitForSpawnCapacity(opts?: {
+  maxWaitMs?: number;
+  onWait?: (reason: string, waitedMs: number) => void;
+  onProceedAnyway?: (reason: string, waitedMs: number) => void;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}): Promise<void> {
+  if (!spawnGateEnabled()) return; // fast path: nothing configured
+  const maxWaitMs = opts?.maxWaitMs ?? getSpawnWaitMs();
+  // Monotonic clock for the deadline — `Date.now()` can step backward (NTP /
+  // suspend) and stretch the fail-open wait far past `maxWaitMs`.
+  const now = opts?.now ?? (() => performance.now());
+  const sleep = opts?.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const start = now();
+  let delay = BACKOFF_BASE_MS;
+  for (;;) {
+    const reason = await spawnRejectionReason();
+    if (!reason) return; // capacity available — admit
+    const waited = now() - start;
+    if (waited >= maxWaitMs) {
+      opts?.onProceedAnyway?.(reason, waited);
+      return; // fail open — never deadlock a workflow
+    }
+    opts?.onWait?.(reason, waited);
+    // Don't oversleep past the deadline.
+    await sleep(Math.min(delay, BACKOFF_CAP_MS, maxWaitMs - waited));
+    delay = Math.min(delay * PHI, BACKOFF_CAP_MS);
+  }
+}

package/ts/subcommands.spec.ts

@@ -43,6 +43,18 @@ describe("subcommands.controlCodeFromName", () => {
     expect(controlCodeFromName("")).toBe("");
   });
 
+  it("maps navigation keys to their ANSI sequences (for ay key / ay select)", async () => {
+    const { controlCodeFromName } = await loadModule();
+    expect(controlCodeFromName("up")).toBe("\x1b[A");
+    expect(controlCodeFromName("down")).toBe("\x1b[B");
+    expect(controlCodeFromName("right")).toBe("\x1b[C");
+    expect(controlCodeFromName("left")).toBe("\x1b[D");
+    expect(controlCodeFromName("space")).toBe(" ");
+    expect(controlCodeFromName("backspace")).toBe("\x7f");
+    expect(controlCodeFromName("pageup")).toBe("\x1b[5~");
+    expect(controlCodeFromName("pagedown")).toBe("\x1b[6~");
+  });
+
   it("supports raw:0xNN escape", async () => {
     const { controlCodeFromName } = await loadModule();
     expect(controlCodeFromName("raw:0x03")).toBe("\x03");
@@ -51,7 +63,27 @@ describe("subcommands.controlCodeFromName", () => {
 
   it("throws on unknown code names", async () => {
     const { controlCodeFromName } = await loadModule();
-    expect(() => controlCodeFromName("nope")).toThrow(/unknown --code/);
+    expect(() => controlCodeFromName("nope")).toThrow(/unknown key\/code/);
+  });
+});
+
+describe("subcommands.menuSelectKeys (ay select cursor arithmetic)", () => {
+  it("sends Downs + Enter to reach an option below the cursor", async () => {
+    const { menuSelectKeys } = await loadModule();
+    expect(menuSelectKeys(1, 3)).toEqual(["down", "down", "enter"]);
+  });
+  it("sends Ups + Enter to reach an option above the cursor", async () => {
+    const { menuSelectKeys } = await loadModule();
+    expect(menuSelectKeys(3, 1)).toEqual(["up", "up", "enter"]);
+  });
+  it("sends only Enter when the cursor already sits on the target", async () => {
+    const { menuSelectKeys } = await loadModule();
+    expect(menuSelectKeys(2, 2)).toEqual(["enter"]);
+  });
+  it("encodes to the exact ANSI byte stream via controlCodeFromName", async () => {
+    const { menuSelectKeys, controlCodeFromName } = await loadModule();
+    const bytes = menuSelectKeys(2, 4).map((k) => controlCodeFromName(k));
+    expect(bytes.join("")).toBe("\x1b[B\x1b[B\r"); // down, down, enter
   });
 });