agent-yes 1.265.4 → 1.266.0

package/ts/parentPingLoop.delivery.spec.ts

@@ -0,0 +1,236 @@
+/**
+ * The half of startParentPingLoop that only runs once a spawner actually
+ * resolves: the poll timer firing a ping, the suppression check, and pingExit.
+ *
+ * Split out from parentPingLoop.spec.ts rather than merged into it because
+ * covering this half means mocking `resolveSpawner`, and those tests are
+ * specifically about what the REAL resolver does with an absent/dead parent —
+ * mocking it there would leave that rule untested.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Resolved per-test: the loop only arms its timer when this yields a spawner.
+let spawner: { cli: string; pid: number; agentId: string | null; cwd: string } | null = null;
+let resolveErr: Error | null = null;
+
+vi.mock("./parentLink.ts", () => ({
+  resolveSpawner: async () => {
+    if (resolveErr) throw resolveErr;
+    return spawner;
+  },
+}));
+
+// deliverPing spawns a real `ay send` child process; stub the delivery but keep
+// buildPingBody real so the body the parent would receive is still exercised.
+const delivered: { target: string; body: string; selfWrapperPid: number }[] = [];
+let deliverOk = true;
+
+vi.mock("./parentPingSend.ts", async () => {
+  const actual = await vi.importActual<typeof import("./parentPingSend.ts")>("./parentPingSend.ts");
+  return {
+    ...actual,
+    deliverPing: async (opts: { target: string; body: string; selfWrapperPid: number }) => {
+      delivered.push(opts);
+      return deliverOk;
+    },
+  };
+});
+
+const CONF = {
+  needsInput: [/❯ ?\d+\./m],
+  working: [/esc to interrupt/],
+  ready: [/^\s*❯\s*$/m],
+};
+
+const self = { cli: "claude", pid: 1, cwd: "/repo" };
+
+async function loadLoop() {
+  return (await import("./parentPingLoop.ts")).startParentPingLoop;
+}
+
+/** Let the `inFlight` promise chain inside send() drain. */
+async function drain() {
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+}
+
+beforeEach(() => {
+  delivered.length = 0;
+  deliverOk = true;
+  resolveErr = null;
+  spawner = { cli: "claude", pid: 42, agentId: "agt_parent", cwd: "/parent" };
+  vi.resetModules();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("startParentPingLoop delivery", () => {
+  const base = {
+    parentPid: 7,
+    selfWrapperPid: 2,
+    self: { ...self },
+    patterns: CONF,
+  };
+
+  it("a pending menu on the first poll reports `stuck` to the parent's agent_id", async () => {
+    vi.useFakeTimers();
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["Do you want to proceed?", "❯ 1. Yes", "  2. No"],
+      pollMs: 1_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await drain();
+
+    expect(delivered).toHaveLength(1);
+    // Routed to the stable agent_id, never the parent's pid.
+    expect(delivered[0].target).toBe("agt_parent");
+    expect(delivered[0].selfWrapperPid).toBe(2);
+    expect(delivered[0].body).toContain("is STUCK");
+    // The tail the parent gets is the screen that justified the report.
+    expect(delivered[0].body).toContain("Do you want to proceed?");
+    loop.stop();
+  });
+
+  it("`never` suppresses the report but still consumes the episode", async () => {
+    vi.useFakeTimers();
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["Do you want to proceed?", "❯ 1. Yes"],
+      pollMs: 1_000,
+      mode: "never",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await drain();
+
+    expect(delivered).toHaveLength(0);
+    loop.stop();
+  });
+
+  it("pingExit reports the exit code and stops the timer", async () => {
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["❯"],
+      pollMs: 60_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await loop.pingExit(3);
+
+    expect(delivered).toHaveLength(1);
+    expect(delivered[0].target).toBe("agt_parent");
+    expect(delivered[0].body).toContain("has EXITED");
+    expect(delivered[0].body).toContain("Exit code: 3");
+  });
+
+  it("pingExit still reports when the screen render throws", async () => {
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => {
+        throw new Error("render race");
+      },
+      pollMs: 60_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await loop.pingExit(null);
+
+    expect(delivered).toHaveLength(1);
+    expect(delivered[0].body).toContain("has EXITED");
+    // No tail to attach, and a null exit code stays off the report entirely.
+    expect(delivered[0].body).not.toContain("Last output:");
+    expect(delivered[0].body).not.toContain("Exit code:");
+  });
+
+  it("an exit that fails to deliver is not thrown at the wrapper's exit path", async () => {
+    deliverOk = false;
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["❯"],
+      pollMs: 60_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await expect(loop.pingExit(1)).resolves.toBeUndefined();
+    expect(delivered).toHaveLength(1);
+  });
+
+  it("reports exactly once — the exit episode is terminal", async () => {
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["❯"],
+      pollMs: 60_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await loop.ready;
+    await loop.pingExit(0);
+    await loop.pingExit(0);
+
+    expect(delivered).toHaveLength(1);
+  });
+
+  it("a spawner lookup that throws is treated as no parent, not a crash", async () => {
+    resolveErr = new Error("registry exploded");
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => ["❯"],
+      mode: "always",
+    });
+
+    await expect(loop.ready).resolves.toBe(false);
+    await expect(loop.pingExit(0)).resolves.toBeUndefined();
+    expect(delivered).toHaveLength(0);
+  });
+
+  it("a screen() hiccup mid-poll skips the tick instead of reporting a false state", async () => {
+    vi.useFakeTimers();
+    let throwNow = true;
+    const startParentPingLoop = await loadLoop();
+    const loop = startParentPingLoop({
+      ...base,
+      screen: () => {
+        if (throwNow) throw new Error("render race");
+        return ["Do you want to proceed?", "❯ 1. Yes"];
+      },
+      pollMs: 1_000,
+      mode: "always",
+      now: () => 1_000,
+    });
+
+    await expect(loop.ready).resolves.toBe(true);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await drain();
+    expect(delivered).toHaveLength(0); // the throwing tick reported nothing
+
+    throwNow = false;
+    await vi.advanceTimersByTimeAsync(1_000);
+    await drain();
+    expect(delivered).toHaveLength(1); // the next good tick still does
+
+    loop.stop();
+  });
+});

package/ts/parentPingLoop.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { classifySelfState, startParentPingLoop } from "./parentPingLoop.ts";
+
+// Mirrors the claude config (rs/default.config.yaml): a numbered menu cursor is
+// a pending question, a spinner marker means work is happening, `❯ ` alone is
+// the idle prompt.
+const CONF = {
+  needsInput: [/❯ ?\d+\./m],
+  working: [/esc to interrupt/],
+  ready: [/^\s*❯\s*$/m],
+};
+
+describe("classifySelfState", () => {
+  it("a working spinner beats everything — a long silent tool call is not done", () => {
+    expect(classifySelfState(["❯ 1. yes", "esc to interrupt"], CONF)).toBe("active");
+    expect(classifySelfState(["❯", "esc to interrupt"], CONF)).toBe("active");
+  });
+
+  it("a pending menu is needs_input", () => {
+    expect(classifySelfState(["Do you want to proceed?", "❯ 1. Yes", "  2. No"], CONF)).toBe(
+      "needs_input",
+    );
+  });
+
+  it("a bare prompt is idle", () => {
+    expect(classifySelfState(["all done", "❯"], CONF)).toBe("idle");
+  });
+
+  it("falls back to active on an unrecognised screen — a false 'idle' is the costly error", () => {
+    expect(classifySelfState(["...something..."], CONF)).toBe("active");
+    expect(classifySelfState([], CONF)).toBe("active");
+    expect(classifySelfState(["❯"], {})).toBe("active");
+  });
+});
+
+describe("startParentPingLoop", () => {
+  const self = { cli: "claude", pid: 1, cwd: "/repo" };
+  const base = {
+    selfWrapperPid: 2,
+    self,
+    patterns: CONF,
+    screen: () => ["❯"],
+  };
+
+  it("never starts a timer for a top-level agent (no parent)", async () => {
+    const loop = startParentPingLoop({ ...base, parentPid: undefined });
+    await expect(loop.ready).resolves.toBe(false);
+    loop.stop();
+  });
+
+  it("treats an unresolvable parent as no parent — a route that goes nowhere is worse than none", async () => {
+    const loop = startParentPingLoop({ ...base, parentPid: 2 ** 30 });
+    await expect(loop.ready).resolves.toBe(false);
+    loop.stop();
+  });
+
+  it("pingExit is a safe no-op when there is nobody to report to", async () => {
+    const loop = startParentPingLoop({ ...base, parentPid: undefined });
+    await expect(loop.pingExit(0)).resolves.toBeUndefined();
+  });
+
+  it("survives a screen() that throws (a render hiccup is not a signal)", async () => {
+    const loop = startParentPingLoop({
+      ...base,
+      parentPid: undefined,
+      screen: () => {
+        throw new Error("render race");
+      },
+    });
+    await expect(loop.ready).resolves.toBe(false);
+    await expect(loop.pingExit(1)).resolves.toBeUndefined();
+  });
+
+  it("stop() before the spawner lookup settles never arms a timer", async () => {
+    const loop = startParentPingLoop({ ...base, parentPid: process.pid });
+    loop.stop();
+    await expect(loop.ready).resolves.toBe(false);
+  });
+});

package/ts/parentPingLoop.ts

@@ -0,0 +1,196 @@
+/**
+ * Wiring for the sub-agent→parent ping: a small poller the wrapper owns for its
+ * OWN agent, feeding `stepParentPing` and delivering whatever it decides.
+ *
+ * Kept out of ts/index.ts (already ~1400 lines) and out of the auto-response
+ * heartbeat: this must not share a tick budget with the thing that answers
+ * permission prompts, and its classification is a different question ("is my
+ * agent done/stuck?") from the heartbeat's ("does this line need a keystroke?").
+ *
+ * No-parent is the common case (a human-launched top-level agent), and it costs
+ * nothing: we resolve the spawner once and simply never start a timer.
+ */
+
+import { classifyNeedsInput } from "./needsInput.ts";
+import { logger } from "./logger.ts";
+import { resolveSpawner } from "./parentLink.ts";
+import { replyTargetOf } from "./initMsg.ts";
+import {
+  DEFAULT_PING_CONFIG,
+  initialPingState,
+  stepParentPing,
+  type PingConfig,
+  type PingState,
+  type SelfState,
+} from "./parentPing.ts";
+import { buildPingBody, deliverPing, type PingSelf } from "./parentPingSend.ts";
+import {
+  isParentWatching,
+  parseReportMode,
+  shouldDeliverReport,
+  type ReportMode,
+} from "./parentWatching.ts";
+
+const POLL_MS = 5_000;
+
+export interface ScreenPatterns {
+  ready?: RegExp[];
+  working?: RegExp[];
+  needsInput?: RegExp[];
+}
+
+/**
+ * Classify the wrapper's own agent from its rendered screen.
+ *
+ * Order matters and is the same precedence `deriveLiveState` uses: a `working`
+ * spinner beats everything (a long silent tool call is NOT done), then a pending
+ * menu, then an idle prompt. Anything unrecognised falls back to `active` —
+ * always the safe default, because a false `active` costs a delayed report while
+ * a false `idle` tells the parent "finished" about an agent mid-task.
+ */
+export function classifySelfState(lines: string[], conf: ScreenPatterns): SelfState {
+  const text = lines.join("\n");
+  if (conf.working?.some((re) => re.test(text))) return "active";
+  if (classifyNeedsInput(lines, conf)) return "needs_input";
+  if (conf.ready?.some((re) => re.test(text))) return "idle";
+  return "active";
+}
+
+export interface ParentPingLoop {
+  /** Stop polling (the exit ping stays available). */
+  stop(): void;
+  /**
+   * Report the agent's termination. Awaited on the wrapper's exit path so the
+   * message is actually handed off before the process goes away.
+   */
+  pingExit(exitCode: number | null): Promise<void>;
+  /** Resolves once the spawner lookup settled — for tests and for `ay` to know
+   *  whether a parent link exists at all. */
+  ready: Promise<boolean>;
+}
+
+/**
+ * Start watching our own agent and reporting to whoever spawned it.
+ *
+ * `screen()` returns the currently-rendered tail lines (the wrapper's xterm
+ * proxy); it is called on every poll, so it must be cheap and must not throw.
+ */
+export function startParentPingLoop(opts: {
+  /** Parent WRAPPER pid inherited via AGENT_YES_PID, or undefined for a root agent. */
+  parentPid: number | undefined;
+  /** This wrapper's own pid — what `ay send` must attribute the report to. */
+  selfWrapperPid: number;
+  self: PingSelf;
+  patterns: ScreenPatterns;
+  screen: () => string[];
+  pollMs?: number;
+  config?: PingConfig;
+  /**
+   * Override `AGENT_YES_REPORT_PARENT`. `auto` (default) stays quiet while the
+   * parent is demonstrably monitoring this child — a parent harness with its own
+   * monitor loop already sees idle/needs_input/working, and an injected report on
+   * top of that interrupts it for nothing. See ts/parentWatching.ts.
+   */
+  mode?: ReportMode;
+  /** Test seam. */
+  now?: () => number;
+}): ParentPingLoop {
+  const cfg = opts.config ?? DEFAULT_PING_CONFIG;
+  const now = opts.now ?? (() => Date.now());
+  const mode: ReportMode = opts.mode ?? parseReportMode(process.env.AGENT_YES_REPORT_PARENT);
+  let state: PingState = initialPingState();
+  let target: string | null = null;
+  let parentAgentPid: number | null = null;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let stopped = false;
+  // One ping in flight at a time: `ay send` can take seconds (paste settle on the
+  // parent's side), and overlapping sends would interleave two reports into one
+  // composer line.
+  let inFlight: Promise<unknown> = Promise.resolve();
+
+  const send = (
+    decision: ReturnType<typeof stepParentPing>["ping"],
+    tail: string | null,
+  ): Promise<void> => {
+    if (!decision || !target) return Promise.resolve();
+    const t = target;
+    inFlight = inFlight
+      .then(async () => {
+        // Checked at SEND time, not at poll time: whether the parent is watching
+        // can change between the edge firing and the report going out, and this
+        // is the moment the answer actually matters. Only reached a handful of
+        // times per agent lifetime, so the lookup's cost is irrelevant.
+        const watching =
+          mode === "auto" && opts.parentPid !== undefined && parentAgentPid !== null
+            ? await isParentWatching(opts.parentPid, parentAgentPid, opts.self.pid, now())
+            : false;
+        if (!shouldDeliverReport({ mode, parentIsWatching: watching, reason: decision.reason })) {
+          logger.debug(
+            `[parent-ping] ${decision.reason} suppressed (mode=${mode}, parent watching=${watching})`,
+          );
+          return;
+        }
+        const body = buildPingBody(decision, opts.self, tail);
+        const ok = await deliverPing({
+          target: t,
+          body,
+          selfWrapperPid: opts.selfWrapperPid,
+        });
+        logger.debug(
+          `[parent-ping] ${decision.reason} attempt ${decision.attempt} → ${t}: ${ok ? "sent" : "FAILED"}`,
+        );
+      })
+      .catch(() => {});
+    return inFlight as Promise<void>;
+  };
+
+  const ready = resolveSpawner(opts.parentPid)
+    .then((spawner) => {
+      if (!spawner || stopped) return false;
+      target = replyTargetOf(spawner);
+      parentAgentPid = spawner.pid;
+      timer = setInterval(() => {
+        let lines: string[] = [];
+        try {
+          lines = opts.screen();
+        } catch {
+          return; // a render hiccup is not a signal
+        }
+        const stepped = stepParentPing(
+          state,
+          { now: now(), state: classifySelfState(lines, opts.patterns) },
+          cfg,
+        );
+        state = stepped.state;
+        if (stepped.ping) void send(stepped.ping, lines.join("\n"));
+      }, opts.pollMs ?? POLL_MS);
+      timer.unref?.();
+      return true;
+    })
+    .catch(() => false);
+
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
+    ready,
+    async pingExit(exitCode) {
+      await ready;
+      this.stop();
+      if (!target) return;
+      let tail: string | null = null;
+      try {
+        tail = opts.screen().join("\n");
+      } catch {
+        /* ignore */
+      }
+      opts.self.exitCode = exitCode;
+      const stepped = stepParentPing(state, { now: now(), state: "exited" }, cfg);
+      state = stepped.state;
+      if (!stepped.ping) return;
+      await send(stepped.ping, tail);
+    },
+  };
+}