@pi-unipi/ralph 2.4.2 → 2.6.0

package/index.ts

@@ -30,6 +30,7 @@ const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 /** Current loop manager instance (recreated on session reload) */
 let manager: RalphLoopManager | null = null;
 
+
 /**
  * Get or create the loop manager for the current context.
  */
@@ -42,9 +43,14 @@ function getManager(ctx: ExtensionContext, pi: ExtensionAPI): RalphLoopManager {
   return manager;
 }
 
+export { buildRalphLoopReminder } from "./reminder.js";
+import { buildRalphLoopReminder, latestRalphReminder, RALPH_REMINDER_TYPE } from "./reminder.js";
+
 export default function (pi: ExtensionAPI) {
-  // Register tools
-  // (Manager will be created lazily on first use)
+  // Register static tool definitions at extension load. Their executors resolve
+  // the session-scoped manager lazily, so schemas never arrive late or reorder
+  // the provider tool array during session_start.
+  registerRalphTools(pi, (ctx) => getManager(ctx, pi));
 
   // Register commands
   registerCommands(pi);
@@ -157,20 +163,13 @@ export default function (pi: ExtensionAPI) {
     const state = mgr.loadState(currentLoop);
     if (!state || state.status !== "active") return;
 
-    const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
-
-    let instructions = `You are in a Ralph loop working on: ${state.taskFile}\n`;
-    if (state.itemsPerIteration > 0) {
-      instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
-    }
-    instructions += `- Update the task file as you progress\n`;
-    instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
-    instructions += `- Otherwise, call ralph_done tool to proceed to next iteration`;
+    const content = buildRalphLoopReminder(state);
+    if (latestRalphReminder(ctx) === content) return;
 
     return {
       message: {
-        customType: "unipi-ralph-loop-reminder",
-        content: `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`,
+        customType: RALPH_REMINDER_TYPE,
+        content,
         display: false,
       },
     };
@@ -187,11 +186,6 @@ export default function (pi: ExtensionAPI) {
     manager = null;
   });
 
-  // Register tools after manager setup
-  pi.on("session_start", async (_event, ctx) => {
-    const mgr = getManager(ctx, pi);
-    registerRalphTools(pi, mgr);
-  });
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ralph",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "Long-running iterative development loops for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -26,9 +26,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "test": "npx tsx --test reminder.test.ts"
+  },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1",
-    "@pi-unipi/info-screen": "2.4.1"
+    "@pi-unipi/core": "2.6.0",
+    "@pi-unipi/info-screen": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",

package/reminder.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  buildRalphLoopReminder,
+  latestRalphReminder,
+  RALPH_REMINDER_TYPE,
+} from "./reminder.ts";
+
+const state = {
+  name: "cache-rollout",
+  iteration: 3,
+  maxIterations: 10,
+  taskFile: ".unipi/ralph/cache-rollout.md",
+  itemsPerIteration: 2,
+};
+
+function context(branch: any[]) {
+  return { sessionManager: { getBranch: () => branch } } as any;
+}
+
+function custom(content: string) {
+  return {
+    type: "custom_message",
+    customType: RALPH_REMINDER_TYPE,
+    content,
+    id: "r1",
+    parentId: null,
+    timestamp: "2026-08-14T00:00:00.000Z",
+    display: false,
+  };
+}
+
+describe("Ralph append-only reminder snapshots", () => {
+  it("is deterministic and explicitly supersedes older reminders", () => {
+    const first = buildRalphLoopReminder(state);
+    const second = buildRalphLoopReminder({ ...state });
+    assert.equal(first, second);
+    assert.match(first, /supersedes all earlier Ralph loop reminders/);
+  });
+
+  it("finds an unchanged retained snapshot for deduplication", () => {
+    const content = buildRalphLoopReminder(state);
+    assert.equal(latestRalphReminder(context([custom(content)])), content);
+  });
+
+  it("returns the newest retained snapshot when state changes", () => {
+    const old = buildRalphLoopReminder({ ...state, iteration: 2 });
+    const current = buildRalphLoopReminder(state);
+    assert.equal(latestRalphReminder(context([custom(old), { ...custom(current), id: "r2" }])), current);
+    assert.notEqual(old, current);
+  });
+
+  it("stops at compaction so current state is reinjected once in the new epoch", () => {
+    const old = buildRalphLoopReminder({ ...state, iteration: 2 });
+    const compaction = {
+      type: "compaction",
+      id: "c1",
+      parentId: "r1",
+      timestamp: "2026-08-14T00:00:01.000Z",
+      summary: `folded: ${old}`,
+      firstKeptEntryId: "r1",
+      tokensBefore: 1000,
+    };
+    assert.equal(latestRalphReminder(context([custom(old), compaction])), null);
+  });
+});

package/reminder.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { RALPH_COMPLETE_MARKER } from "@pi-unipi/core";
+
+export const RALPH_REMINDER_TYPE = "unipi-ralph-loop-reminder";
+
+export interface RalphReminderInput {
+  name: string;
+  iteration: number;
+  maxIterations: number;
+  taskFile: string;
+  itemsPerIteration: number;
+}
+
+/** Build the exact deterministic hidden reminder used by the live hook. */
+export function buildRalphLoopReminder(state: RalphReminderInput): string {
+  const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
+  let instructions = "This snapshot supersedes all earlier Ralph loop reminders.\n";
+  instructions += `You are in a Ralph loop working on: ${state.taskFile}\n`;
+  if (state.itemsPerIteration > 0) {
+    instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
+  }
+  instructions += "- Update the task file as you progress\n";
+  instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
+  instructions += "- Otherwise, call ralph_done tool to proceed to next iteration";
+  return `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`;
+}
+
+export function latestRalphReminder(ctx: Pick<ExtensionContext, "sessionManager">): string | null {
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === RALPH_REMINDER_TYPE) {
+      return typeof entry.content === "string" ? entry.content : null;
+    }
+    // A compacted summary may contain the old reminder but no longer retains a
+    // dedicated custom entry. Inject the current snapshot once in the new epoch.
+    if (entry.type === "compaction") break;
+  }
+  return null;
+}

package/tools.ts

@@ -9,10 +9,12 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { RALPH_COMPLETE_MARKER, RALPH_DEFAULTS, RALPH_TOOLS } from "@pi-unipi/core";
 import { RalphLoopManager, DEFAULT_REFLECT_INSTRUCTIONS } from "./ralph-loop.js";
 
+type ManagerProvider = (ctx: ExtensionContext) => RalphLoopManager;
+
 /**
  * Register ralph_start and ralph_done tools.
  */
-export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager): void {
+export function registerRalphTools(pi: ExtensionAPI, getManager: ManagerProvider): void {
   // --- ralph_start tool ---
   pi.registerTool({
     name: RALPH_TOOLS.START,
@@ -44,6 +46,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       const taskFile = `.unipi/ralph/${params.name.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`;
 
       if (manager.loadState(params.name)?.status === "active") {
@@ -92,6 +95,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
     ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       if (!manager.getCurrentLoop()) {
         return {
           content: [{ type: "text", text: "No active Ralph loop." }],