@jaybeeuu/agent-cortex 2.7.0 → 2.8.0

package/extensions/post-merge-watch/README.md

@@ -0,0 +1,133 @@
+# Post-Merge Watch Extension
+
+Wakes an idle PI session with the verdict of a post-merge CI run.
+
+A human merges the feature PR, and the CI run for the merge commit decides what
+happens next: nothing, a fix, or a revert. That merge lands outside the session,
+so nothing tells the agent when the run concludes. This extension polls the
+deterministic post-merge check and delivers the verdict as a follow-up message,
+which starts a turn in an idle session.
+
+## Usage
+
+```bash
+pi --post-merge-watch <bead>
+```
+
+| Input | Meaning |
+| --- | --- |
+| `--post-merge-watch <bead>` | Watch the post-merge check for this bead and wake the session with the verdict |
+| `AGENT_CORTEX_POST_MERGE_CHECK` | Path of the check script, when the shipped one is not the one to run |
+
+The flag is registered at load time, so it is accepted on the command line. A
+session without the flag starts no watch, spawns no process, and writes no state.
+
+The default script is `skills/workflow/ralph/scripts/post-merge-check.mjs`,
+resolved relative to this extension's own file. In a staged install
+(`extensions/` beside `skills/`) and in a checkout of this repository the same
+relative path resolves, so no absolute path is baked in.
+
+## What it does
+
+1. At session start, with the flag set, it records the watch and runs the check.
+2. It runs the check every 15 seconds, up to 40 times (about 10 minutes).
+3. When the check exits `0` (passed) or `1` (failed), or the attempt cap is
+   reached, it sends one message and stops watching.
+
+Each invocation passes `--wait 0`, so the script reports once instead of waiting
+inside itself: the poll interval and the bound belong to this extension, and a
+stopped watch never blocks on a running child process.
+
+The wake uses the confirmed PI signature
+`pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true })`: an idle
+session starts a turn from it, and a session in the middle of a turn reads it
+after that turn instead of being interrupted.
+
+The message names the bead, the verdict, the exit code, the reason, the run URL,
+the project, and the number of checks made. It carries the same fields as message
+`details`, so a renderer can read them without parsing the text.
+
+## What it never does
+
+- **No verdict logic.** The check's exit code is the verdict: `0` passed, `1`
+  failed, every other code (including a timeout kill) inconclusive. The run URL
+  and the reason are read from the script's JSON report and forwarded verbatim.
+  The extension never decides whether a run passed and never re-runs a workflow.
+- **No model call.** No prompt, no summarisation, no title generation. One turn
+  happens only because the delivered message starts one.
+- **No `@earendil-works/*` value import.** Types only, so the staged install
+  loads with pi absent from the extension's own `node_modules`
+  (`test/pi-extensions-load.test.mjs` proves this).
+- **No second watch for the same bead.** A session reload re-fires
+  `session_start`; the extension starts one watch per bead.
+
+## State
+
+| Item | Value |
+| --- | --- |
+| Directory | `~/.pi/agent-cortex/post-merge-watch/` |
+| File name | `<project dir name>-<bead>-<digest of full project path and bead>.json` |
+| Written | At watch start, then after each poll |
+| Removed | When the watch settles, when the session shuts down, and again if a write was still in flight |
+
+The digest covers the whole project path, so two checkouts whose directory names
+match — or two projects watching the same bead — never share a file. A watch that
+is still polling is the only thing the directory should hold.
+
+The write and the removal can race: a stop removes the file, and a write that is
+still in flight then recreates it. The write therefore re-checks whether the
+watch stopped once it completes, and removes the file again, so a stop cannot
+leave a state file behind. One narrow case survives: a write that **fails** while
+a stop is in progress returns before that re-check, so it can leave a partial
+file. No code reads the directory, so a partial file is cosmetic; do not read it
+as a live watch.
+
+The in-flight record is diagnostic: it names the bead, the project, the script,
+the pid, the attempt count, and the last exit code and reason. Nothing reads it
+back, so a watch never resumes from it; a new session with the same flag starts a
+new watch.
+
+## Bounds and shutdown
+
+| Bound | Value |
+| --- | --- |
+| Poll interval | 15 s |
+| Checks | 40 |
+| One check invocation | 120 s, then pi kills it |
+
+The pending timer is unref'd, so a watch never holds the host process open. On
+`session_shutdown` the timer is cancelled, a check already in flight is ignored,
+and the state file is removed: an abandoned watch wakes nobody and leaves nothing
+behind.
+
+## What has been proven
+
+The wake path has been run once end to end against a stub check script: the RPC
+wake itself was reproduced (`agent_settled` → `agent_start`, the custom message
+arriving with no client prompt), and a real model turn ran on it. That run did not
+read a real CI run, because the shipped `post-merge-check.mjs` was replaced by a
+stub: the poll-and-wake path is proven, and the check's own judgement is covered
+by `test/post-merge-check.test.mjs`, not by any test here. Treat the pair as one
+path only after a watch has read a genuine merge-commit run.
+
+## Claude Code parity
+
+PI-only. Claude Code has its own watch tools, which the Claude side uses instead of
+an extension.
+
+## Development
+
+```bash
+pnpm test        # the poll lifecycle, the wake payload, the state file, the wiring
+pnpm typecheck   # tsc --noEmit
+```
+
+`watch.test.ts` drives the whole lifecycle with a scheduler it steps by hand and a
+check runner that returns scripted exit codes, so no test sleeps or waits on a
+timer. `index.test.ts` drives the extension through a partial `ExtensionAPI`
+double; the complete-literal guard that fails `tsc` when pi's interface grows is
+`extensions/agent-modes/index.test.ts`.
+
+To watch the poll end to end against a script that is not the shipped one, point
+`AGENT_CORTEX_POST_MERGE_CHECK` at any executable that follows the check's
+contract: JSON on stdout and exit `0`/`1`/`2`.

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"
+  }
+}