@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/extensions/post-merge-watch/index.test.ts

@@ -0,0 +1,247 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createTempRoot } from "../../test/helpers/temp-root.mjs";
+import postMergeWatchExtension, { CHECK_SCRIPT_ENV, WATCH_FLAG, checkScript } from "./index.ts";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const tempRoot = createTempRoot("post-merge-watch-index-");
+
+interface FlagRegistration {
+  name: string;
+  options: { description?: string; type: "string" | "boolean"; default?: string | boolean };
+}
+
+interface SentMessage {
+  message: { customType: string; content: string | unknown[]; display: boolean; details?: unknown };
+  options: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" } | undefined;
+}
+
+interface ExecCall {
+  command: string;
+  args: string[];
+  options: { cwd?: string; timeout?: number } | undefined;
+}
+
+/** An event handler as `pi.on` recorded it, called through `Reflect.apply`. */
+type RecordedHandler = (...args: never[]) => unknown;
+
+interface FakePi {
+  pi: ExtensionAPI;
+  flags: FlagRegistration[];
+  sent: SentMessage[];
+  execs: ExecCall[];
+  notifications: Array<{ message: string; type: string | undefined }>;
+  /** Fire every handler pi registered for `event`. */
+  fire(event: string, payload: unknown, context: unknown): Promise<void>;
+}
+
+/**
+ * A double for the five `ExtensionAPI` members this extension reaches.
+ *
+ * Deliberately partial: the complete-literal guard is
+ * `extensions/agent-modes/index.test.ts`, whose fake fails `tsc` when pi's
+ * interface grows a member.
+ */
+function createFakePi(options: {
+  flag: string | undefined;
+  scriptExitCode: number;
+  scriptStdout?: string;
+}): FakePi {
+  const flags: FlagRegistration[] = [];
+  const sent: SentMessage[] = [];
+  const execs: ExecCall[] = [];
+  const notifications: Array<{ message: string; type: string | undefined }> = [];
+  const handlers = new Map<string, RecordedHandler[]>();
+
+  const pi = {
+    registerFlag: (name: string, registration: FlagRegistration["options"]) => {
+      flags.push({ name, options: registration });
+    },
+    getFlag: (name: string) => (name === WATCH_FLAG ? options.flag : undefined),
+    on: (event: string, handler: RecordedHandler) => {
+      handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+      return () => {};
+    },
+    exec: async (command: string, args: string[], execOptions: ExecCall["options"]) => {
+      execs.push({ command, args, options: execOptions });
+      return {
+        stdout: options.scriptStdout ?? "",
+        stderr: "",
+        code: options.scriptExitCode,
+        killed: false,
+        truncated: false,
+      };
+    },
+    sendMessage: (message: SentMessage["message"], sendOptions?: SentMessage["options"]) => {
+      sent.push({ message, options: sendOptions });
+    },
+  } as unknown as ExtensionAPI;
+
+  return {
+    pi,
+    flags,
+    sent,
+    execs,
+    notifications,
+    async fire(event, payload, context) {
+      for (const handler of handlers.get(event) ?? []) {
+        await Reflect.apply(handler, undefined, [
+          payload,
+          {
+            cwd: "/projects/one",
+            ui: { notify: (message: string, type?: string) => notifications.push({ message, type }) },
+            ...(context as object),
+          },
+        ]);
+      }
+    },
+  };
+}
+
+/** The startup event pi sends before a session is usable. */
+const SESSION_START = { type: "session_start", reason: "startup" } as const;
+
+/** Run one session start with `HOME` pointed at a temp root, so no test reads the real home. */
+async function withTempHome<T>(run: (home: string) => Promise<T>): Promise<T> {
+  const home = await tempRoot.createWorkspace();
+  const previousHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    return await run(home);
+  } finally {
+    process.env.HOME = previousHome;
+  }
+}
+
+/** The state directory the extension uses for a given home. */
+function stateDirFor(home: string): string {
+  return join(home, ".pi", "agent-cortex", "post-merge-watch");
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Flag registration ───────────────────────────────────────────────────────
+
+describe("post-merge-watch extension", () => {
+  it("registers its CLI flag in the factory, before any session starts", async () => {
+    const fake = createFakePi({ flag: undefined, scriptExitCode: 2 });
+
+    postMergeWatchExtension(fake.pi);
+
+    assert.deepEqual(
+      fake.flags.map((flag) => ({ name: flag.name, type: flag.options.type })),
+      [{ name: "post-merge-watch", type: "string" }],
+    );
+  });
+
+  it("resolves the shipped check script without a hardcoded absolute path", () => {
+    const previous = process.env[CHECK_SCRIPT_ENV];
+    delete process.env[CHECK_SCRIPT_ENV];
+    try {
+      assert.match(checkScript(), /skills[/\\]workflow[/\\]ralph[/\\]scripts[/\\]post-merge-check\.mjs$/);
+    } finally {
+      if (previous !== undefined) process.env[CHECK_SCRIPT_ENV] = previous;
+    }
+  });
+
+  it("polls the script the environment names, so an install can be pointed at a stub", async () => {
+    const previous = process.env[CHECK_SCRIPT_ENV];
+    process.env[CHECK_SCRIPT_ENV] = "/stub/post-merge-check.mjs";
+    try {
+      assert.equal(checkScript(), "/stub/post-merge-check.mjs");
+    } finally {
+      if (previous === undefined) delete process.env[CHECK_SCRIPT_ENV];
+      else process.env[CHECK_SCRIPT_ENV] = previous;
+    }
+  });
+
+  // ─── Session lifecycle ─────────────────────────────────────────────────────
+
+  it("starts one watch at session start and wakes the session when the check settles", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({
+        flag: "agnt-ctx-86u4.2",
+        scriptExitCode: 1,
+        scriptStdout: JSON.stringify({ reason: "run-failed", runs: [{ url: "https://gh/run/9" }] }),
+      });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.equal(fake.execs.length, 1);
+      assert.deepEqual(
+        { args: fake.execs[0].args.slice(1), cwd: fake.execs[0].options?.cwd },
+        { args: ["--wait", "0"], cwd: "/projects/one" },
+      );
+      assert.equal(fake.sent.length, 1);
+      assert.deepEqual(fake.sent[0].options, { deliverAs: "followUp", triggerTurn: true });
+      assert.match(fake.sent[0].message.content as string, /agnt-ctx-86u4\.2/);
+      assert.deepEqual(fake.sent[0].message.details, {
+        bead: "agnt-ctx-86u4.2",
+        verdict: "failed",
+        runUrl: "https://gh/run/9",
+        exitCode: 1,
+        reason: "run-failed",
+        attempts: 1,
+        project: "/projects/one",
+      });
+    });
+  });
+
+  it("starts no watch when the flag is absent", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({ flag: undefined, scriptExitCode: 1 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.deepEqual(fake.execs, []);
+      assert.equal(await exists(stateDirFor(home)), false);
+    });
+  });
+
+  it("records the watch under the agent-cortex state directory, then clears it on session shutdown", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({ flag: "agnt-ctx-86u4.2", scriptExitCode: 2 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.deepEqual(
+        (await readdir(stateDirFor(home))).length,
+        1,
+        "the in-flight watch is recorded under ~/.pi/agent-cortex",
+      );
+      assert.equal(fake.sent.length, 0, "no verdict yet, so no wake");
+
+      await fake.fire("session_shutdown", { type: "session_shutdown", reason: "quit" }, {});
+
+      assert.deepEqual(await readdir(stateDirFor(home)), [], "an abandoned watch leaves no state file");
+      assert.deepEqual(fake.sent, [], "an abandoned watch wakes nobody");
+    });
+  });
+
+  it("starts no second watch when the session reloads for the same bead", async () => {
+    await withTempHome(async () => {
+      const fake = createFakePi({ flag: "agnt-ctx-86u4.2", scriptExitCode: 2 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+      await fake.fire("session_start", { type: "session_start", reason: "reload" }, {});
+
+      assert.equal(fake.execs.length, 1);
+    });
+  });
+});

package/extensions/post-merge-watch/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Post-merge watch extension.
+ *
+ * A human merges the feature PR, and the CI run for the merge commit decides
+ * what happens next. Nothing tells the agent when that run concludes: the merge
+ * happens outside the session, and by the time the run settles the agent is idle.
+ * This extension makes the session wake up with the verdict.
+ *
+ * It polls the deterministic check script
+ * (`skills/workflow/ralph/scripts/post-merge-check.mjs`) on a timer and, when the
+ * script reports a verdict, sends one follow-up message — `deliverAs:
+ * "followUp"`, `triggerTurn: true` — so an idle session starts a turn with the
+ * result. The script owns the verdict; this extension runs it and forwards the
+ * exit code. It makes no model call.
+ *
+ * Opt-in per session through the `--post-merge-watch <bead>` flag. State lives
+ * under `~/.pi/agent-cortex/post-merge-watch/`, one file per project and bead,
+ * and is removed when the watch settles or the session shuts down.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { PostMergeWatch, DEFAULT_INTERVAL_MS, DEFAULT_MAX_ATTEMPTS } from "./watch.ts";
+import type { CheckRun, CheckInvocation, WakeMessage } from "./watch.ts";
+
+/** The CLI flag that starts a watch: `--post-merge-watch <bead>`. */
+export const WATCH_FLAG = "post-merge-watch";
+
+/**
+ * Environment override for the check script path. The default resolves against
+ * this module, so the staged pi package (`extensions/` beside `skills/`) and a
+ * checkout of this repository both find the shipped script without a hardcoded
+ * absolute path.
+ */
+export const CHECK_SCRIPT_ENV = "AGENT_CORTEX_POST_MERGE_CHECK";
+
+/** The check script's location in a staged install and in this repository. */
+const DEFAULT_CHECK_SCRIPT = new URL(
+  "../../skills/workflow/ralph/scripts/post-merge-check.mjs",
+  import.meta.url,
+);
+
+/** How long one check invocation may take before pi kills it. */
+const CHECK_TIMEOUT_MS = 120_000;
+
+/** The state directory, under the agent-cortex global area, never in the project. */
+export function stateDir(): string {
+  return join(homedir(), ".pi", "agent-cortex", "post-merge-watch");
+}
+
+/** The check script this extension polls. */
+export function checkScript(): string {
+  const override = process.env[CHECK_SCRIPT_ENV];
+  return override !== undefined && override !== "" ? override : fileURLToPath(DEFAULT_CHECK_SCRIPT);
+}
+
+export default function postMergeWatchExtension(pi: ExtensionAPI): void {
+  // Registered here, in the factory: pi matches parsed CLI flags against the
+  // extensions loaded at startup, so a flag registered from `session_start` is
+  // rejected as an unknown option.
+  pi.registerFlag(WATCH_FLAG, {
+    description: "Watch the post-merge check for a bead and wake the session with the verdict",
+    type: "string",
+  });
+
+  /** One watch per bead, so a reloaded session does not start a second one. */
+  const watches = new Map<string, PostMergeWatch>();
+
+  const runCheck = async (invocation: CheckInvocation): Promise<CheckRun> => {
+    const result = await pi.exec(process.execPath, [invocation.script, ...invocation.args], {
+      cwd: invocation.cwd,
+      timeout: CHECK_TIMEOUT_MS,
+    });
+    return { code: result.code, stdout: result.stdout, stderr: result.stderr, killed: result.killed };
+  };
+
+  /**
+   * The verdict goes out as a follow-up message with `triggerTurn`, so a session
+   * that is idle starts a turn and one that is busy reads it after the turn in
+   * progress instead of interrupting it.
+   */
+  const deliver = (message: WakeMessage): void => {
+    pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+  };
+
+  const watchedBead = (): string | undefined => {
+    const value = pi.getFlag(WATCH_FLAG);
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    for (const [bead, watch] of watches) {
+      if (!watch.active) watches.delete(bead);
+    }
+
+    const bead = watchedBead();
+    if (bead === undefined || watches.has(bead)) return;
+
+    const watch = new PostMergeWatch({
+      bead,
+      project: ctx.cwd,
+      script: checkScript(),
+      stateDir: stateDir(),
+      runCheck,
+      deliver,
+      intervalMs: DEFAULT_INTERVAL_MS,
+      maxAttempts: DEFAULT_MAX_ATTEMPTS,
+      warn: (message) => ctx.ui.notify(message, "warning"),
+    });
+
+    watches.set(bead, watch);
+    await watch.start();
+  });
+
+  pi.on("session_shutdown", async () => {
+    const stopping = [...watches.values()].map((watch) => watch.stop());
+    watches.clear();
+    await Promise.all(stopping);
+  });
+}

package/extensions/post-merge-watch/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@agent-cortex/post-merge-watch",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm watch.test.ts index.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}