@pi-unipi/ralph 0.1.1

package/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: ralph
+description: >
+  Long-running iterative development loops. Run arbitrarily-long tasks without
+  diluting model attention. Triggers: ralph, ralph loop, iterative loop,
+  long-running task, development loop.
+---
+
+# Ralph Loop
+
+Long-running iterative development loops. Run complex tasks across multiple iterations with reflection checkpoints.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:ralph start <name> [options]` | Start a new loop |
+| `/unipi:ralph stop` | Pause current loop |
+| `/unipi:ralph resume <name>` | Resume a paused loop |
+| `/unipi:ralph status` | Show all loops |
+| `/unipi:ralph cancel <name>` | Delete loop state |
+| `/unipi:ralph archive <name>` | Move loop to archive |
+| `/unipi:ralph clean [--all]` | Clean completed loops |
+| `/unipi:ralph list --archived` | Show archived loops |
+| `/unipi:ralph nuke [--yes]` | Delete all ralph data |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ralph_start` | Start a ralph loop (LLM-callable) |
+| `ralph_done` | Signal iteration complete, request next |
+
+## Options
+
+- `--max-iterations N` — Stop after N iterations (default: 50)
+- `--items-per-iteration N` — Process N items per iteration
+- `--reflect-every N` — Reflection checkpoint every N iterations
+
+## How It Works
+
+1. **Start** — Create a task file with goals and checklist
+2. **Iterate** — LLM works on task, updates checklist, calls `ralph_done`
+3. **Reflect** — Every N iterations, pause and assess progress
+4. **Complete** — When done, LLM outputs `COMPLETE` marker
+
+## Integration with Workflow
+
+When `@unipi/workflow` is present:
+- `/unipi:work` suggests ralph for large tasks
+- Ralph loops emit events that workflow can track
+- Ralph state is available to info-screen (when present)
+
+## Task File Format
+
+```markdown
+# Task
+
+{Description}
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Checklist
+- [ ] Item 1
+- [ ] Item 2
+- [x] Completed item
+
+## Notes
+{Progress notes}
+```
+
+## State
+
+Loop state stored in `.unipi/ralph/` directory:
+- `.unipi/ralph/{name}.md` — Task file
+- `.unipi/ralph/{name}.state.json` — Loop state
+- `.unipi/ralph/archive/` — Completed loops
+
+## Tips
+
+- Use `--items-per-iteration` for large checklists
+- Use `--reflect-every 10` for long-running tasks
+- Press ESC to pause, send message to resume
+- Task file is updated each iteration — check it for progress

package/index.ts

@@ -0,0 +1,548 @@
+/**
+ * @unipi/ralph — Long-running iterative development loops
+ *
+ * Adapted from pi-ralph-wiggum with unipi event integration.
+ * Emits MODULE_READY, RALPH_LOOP_START/END events.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  RALPH_COMPLETE_MARKER,
+  RALPH_TOOLS,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+
+// Get info registry from global
+function getInfoRegistry() {
+  const g = globalThis as any;
+  return g.__unipi_info_registry;
+}
+import { RalphLoopManager } from "./ralph-loop.js";
+import { registerRalphTools } from "./tools.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+/** Current loop manager instance (recreated on session reload) */
+let manager: RalphLoopManager | null = null;
+
+/**
+ * Get or create the loop manager for the current context.
+ */
+function getManager(ctx: ExtensionContext, pi: ExtensionAPI): RalphLoopManager {
+  if (!manager) {
+    manager = new RalphLoopManager(ctx, (event, payload) =>
+      emitEvent(pi, event, payload),
+    );
+  }
+  return manager;
+}
+
+export default function (pi: ExtensionAPI) {
+  // Register tools
+  // (Manager will be created lazily on first use)
+
+  // Register commands
+  registerCommands(pi);
+
+  // Session lifecycle
+  pi.on("session_start", async (_event, ctx) => {
+    manager = null; // Force re-creation with new context
+    const mgr = getManager(ctx, pi);
+
+    // Rehydrate from disk
+    mgr.rehydrate();
+
+    // Announce module
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.RALPH,
+      version: VERSION,
+      commands: [
+        "unipi:ralph-start",
+        "unipi:ralph-stop",
+        "unipi:ralph-resume",
+        "unipi:ralph-status",
+        "unipi:ralph-cancel",
+        "unipi:ralph-archive",
+        "unipi:ralph-clean",
+        "unipi:ralph-list",
+        "unipi:ralph-nuke",
+      ],
+      tools: [RALPH_TOOLS.START, RALPH_TOOLS.DONE],
+    });
+
+    // Register info group
+    const registry = getInfoRegistry();
+    if (registry) {
+      registry.registerGroup({
+        id: "ralph",
+        name: "Ralph Loops",
+        icon: "🔄",
+        priority: 70,
+        config: {
+          showByDefault: true,
+          stats: [
+            { id: "activeLoops", label: "Active Loops", show: true },
+            { id: "totalIterations", label: "Total Iterations", show: true },
+            { id: "status", label: "Status", show: true },
+          ],
+        },
+        dataProvider: async () => {
+          const currentLoop = mgr.getCurrentLoop();
+          if (!currentLoop) {
+            return {
+              activeLoops: { value: "0" },
+              totalIterations: { value: "0" },
+              status: { value: "idle" },
+            };
+          }
+
+          const state = mgr.loadState(currentLoop);
+          return {
+            activeLoops: { value: "1" },
+            totalIterations: { value: String(state?.iteration ?? 0) },
+            status: { value: state?.status ?? "unknown" },
+          };
+        },
+      });
+    }
+  });
+
+  // Agent lifecycle — check for completion marker
+  pi.on("agent_end", async (event, ctx) => {
+    const mgr = getManager(ctx, pi);
+    const currentLoop = mgr.getCurrentLoop();
+    if (!currentLoop) return;
+
+    const state = mgr.loadState(currentLoop);
+    if (!state || state.status !== "active") return;
+
+    // Check for completion marker in last assistant message
+    const lastAssistant = [...event.messages]
+      .reverse()
+      .find((m) => m.role === "assistant");
+    const text =
+      lastAssistant && Array.isArray(lastAssistant.content)
+        ? lastAssistant.content
+            .filter(
+              (c): c is { type: "text"; text: string } => c.type === "text",
+            )
+            .map((c) => c.text)
+            .join("\n")
+        : "";
+
+    if (text.includes(RALPH_COMPLETE_MARKER)) {
+      mgr.completeLoop(
+        state,
+        `───────────────────────────────────────────────────────────────────────
+✅ RALPH LOOP COMPLETE: ${state.name} | ${state.iteration} iterations
+───────────────────────────────────────────────────────────────────────`,
+      );
+    }
+  });
+
+  // Inject ralph instructions when loop is active
+  pi.on("before_agent_start", async (event, ctx) => {
+    const mgr = getManager(ctx, pi);
+    const currentLoop = mgr.getCurrentLoop();
+    if (!currentLoop) return;
+
+    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`;
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `\n[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`,
+    };
+  });
+
+  // Save state on shutdown
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (!manager) return;
+    const currentLoop = manager.getCurrentLoop();
+    if (currentLoop) {
+      const state = manager.loadState(currentLoop);
+      if (state) manager.saveState(state);
+    }
+    manager = null;
+  });
+
+  // Register tools after manager setup
+  pi.on("session_start", async (_event, ctx) => {
+    const mgr = getManager(ctx, pi);
+    registerRalphTools(pi, mgr);
+  });
+}
+
+/**
+ * Register ralph commands.
+ */
+function registerCommands(pi: ExtensionAPI): void {
+  const HELP = `Ralph Loop — Long-running development loops
+
+Commands:
+  /unipi:ralph start <name|path> [options]  Start a new loop
+  /unipi:ralph stop                         Pause current loop
+  /unipi:ralph resume <name>                Resume a paused loop
+  /unipi:ralph status                       Show all loops
+  /unipi:ralph cancel <name>                Delete loop state
+  /unipi:ralph archive <name>               Move loop to archive
+  /unipi:ralph clean [--all]                Clean completed loops
+  /unipi:ralph list --archived              Show archived loops
+  /unipi:ralph nuke [--yes]                 Delete all ralph data
+
+Options:
+  --items-per-iteration N  Suggest N items per turn (prompt hint)
+  --reflect-every N        Reflect every N iterations
+  --max-iterations N       Stop after N iterations (default 50)
+
+To stop: press ESC to interrupt, then run /unipi:ralph-stop when idle`;
+
+  pi.registerCommand("unipi:ralph", {
+    description: "Ralph loop commands (start, stop, resume, status, etc.)",
+    handler: async (args, ctx) => {
+      const parts = args.trim().split(/\s+/);
+      const cmd = parts[0];
+      const rest = parts.slice(1).join(" ");
+
+      // We need manager for most commands
+      // For 'start', we'll handle it specially
+      if (cmd === "start") {
+        handleStart(rest, ctx, pi);
+      } else if (cmd === "stop") {
+        handleStop(ctx, pi);
+      } else if (cmd === "resume") {
+        handleResume(rest, ctx, pi);
+      } else if (cmd === "status" || cmd === "list") {
+        handleList(rest, ctx, pi);
+      } else if (cmd === "cancel") {
+        handleCancel(rest, ctx, pi);
+      } else if (cmd === "archive") {
+        handleArchive(rest, ctx, pi);
+      } else if (cmd === "clean") {
+        handleClean(rest, ctx, pi);
+      } else if (cmd === "nuke") {
+        handleNuke(rest, ctx, pi);
+      } else {
+        if (ctx.hasUI) ctx.ui.notify(HELP, "info");
+      }
+    },
+  });
+
+  // Dedicated stop command for idle-only use
+  pi.registerCommand("unipi:ralph-stop", {
+    description: "Stop active Ralph loop (idle only)",
+    handler: async (_args, ctx) => {
+      handleStop(ctx, pi);
+    },
+  });
+}
+
+function handleStart(rest: string, ctx: ExtensionContext, pi: ExtensionAPI): void {
+  const tokens = rest.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+  let name = "";
+  let maxIterations = 50;
+  let itemsPerIteration = 0;
+  let reflectEvery = 0;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    const next = tokens[i + 1];
+    if (tok === "--max-iterations" && next) {
+      maxIterations = parseInt(next, 10) || 0;
+      i++;
+    } else if (tok === "--items-per-iteration" && next) {
+      itemsPerIteration = parseInt(next, 10) || 0;
+      i++;
+    } else if (tok === "--reflect-every" && next) {
+      reflectEvery = parseInt(next, 10) || 0;
+      i++;
+    } else if (!tok.startsWith("--")) {
+      name = tok.replace(/^"|"$/g, "");
+    }
+  }
+
+  if (!name) {
+    if (ctx.hasUI)
+      ctx.ui.notify(
+        "Usage: /unipi:ralph start <name|path> [--items-per-iteration N] [--reflect-every N] [--max-iterations N]",
+        "warning",
+      );
+    return;
+  }
+
+  const mgr = getManager(ctx, pi);
+  const isPath = name.includes("/") || name.includes("\\");
+  const loopName = isPath
+    ? name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_")
+    : name;
+  const taskFile = isPath ? name : `.unipi/ralph/${loopName}.md`;
+
+  const existing = mgr.loadState(loopName);
+  if (existing?.status === "active") {
+    if (ctx.hasUI)
+      ctx.ui.notify(
+        `Loop "${loopName}" is already active. Use /unipi:ralph resume ${loopName}`,
+        "warning",
+      );
+    return;
+  }
+
+  // Check if task file exists, create if not
+  const fullPath = require("node:path").resolve(ctx.cwd, taskFile);
+  const fs = require("node:fs");
+  if (!fs.existsSync(fullPath)) {
+    const { ensureDir } = require("@pi-unipi/core");
+    ensureDir(fullPath);
+    fs.writeFileSync(
+      fullPath,
+      `# Task\n\nDescribe your task here.\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n\n## Notes\n(Update this as you work)\n`,
+      "utf-8",
+    );
+    if (ctx.hasUI) ctx.ui.notify(`Created task file: ${taskFile}`, "info");
+  }
+
+  const { tryRead } = require("@pi-unipi/core");
+  const content = tryRead(fullPath);
+  if (!content) {
+    if (ctx.hasUI) ctx.ui.notify(`Could not read task file: ${taskFile}`, "error");
+    return;
+  }
+
+  const state = mgr.startLoop(loopName, taskFile, content, {
+    maxIterations,
+    itemsPerIteration,
+    reflectEvery,
+  });
+
+  pi.sendUserMessage(mgr.buildPrompt(state, content, false));
+}
+
+function handleStop(ctx: ExtensionContext, pi: ExtensionAPI): void {
+  if (!ctx.isIdle()) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        "Agent is busy. Press ESC to interrupt, then run /unipi:ralph-stop.",
+        "warning",
+      );
+    }
+    return;
+  }
+
+  const mgr = getManager(ctx, pi);
+  let currentLoop = mgr.getCurrentLoop();
+  let state = currentLoop ? mgr.loadState(currentLoop) : null;
+
+  if (!state) {
+    const active = mgr.listLoops().find((l) => l.status === "active");
+    if (!active) {
+      if (ctx.hasUI) ctx.ui.notify("No active Ralph loop", "warning");
+      return;
+    }
+    state = active;
+  }
+
+  if (state.status !== "active") {
+    if (ctx.hasUI)
+      ctx.ui.notify(`Loop "${state.name}" is not active`, "warning");
+    return;
+  }
+
+  mgr.stopLoop(
+    state,
+    `Stopped Ralph loop: ${state.name} (iteration ${state.iteration})`,
+  );
+}
+
+function handleResume(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const loopName = rest.trim();
+  if (!loopName) {
+    if (ctx.hasUI) ctx.ui.notify("Usage: /unipi:ralph resume <name>", "warning");
+    return;
+  }
+
+  const mgr = getManager(ctx, pi);
+  const state = mgr.resumeLoop(loopName);
+  if (!state) {
+    if (ctx.hasUI) ctx.ui.notify(`Loop "${loopName}" not found or completed`, "error");
+    return;
+  }
+
+  if (ctx.hasUI)
+    ctx.ui.notify(
+      `Resumed: ${loopName} (iteration ${state.iteration})`,
+      "info",
+    );
+
+  const content = mgr.tryReadTask(state);
+  if (!content) {
+    if (ctx.hasUI)
+      ctx.ui.notify(`Could not read task file: ${state.taskFile}`, "error");
+    return;
+  }
+
+  const needsReflection =
+    state.reflectEvery > 0 &&
+    state.iteration > 1 &&
+    (state.iteration - 1) % state.reflectEvery === 0;
+  pi.sendUserMessage(mgr.buildPrompt(state, content, needsReflection));
+}
+
+function handleList(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const archived = rest.trim() === "--archived";
+  const mgr = getManager(ctx, pi);
+  const loops = mgr.listLoops(archived);
+
+  if (loops.length === 0) {
+    if (ctx.hasUI)
+      ctx.ui.notify(
+        archived
+          ? "No archived loops"
+          : "No loops found. Use /unipi:ralph list --archived for archived.",
+        "info",
+      );
+    return;
+  }
+
+  const label = archived ? "Archived loops" : "Ralph loops";
+  if (ctx.hasUI)
+    ctx.ui.notify(
+      `${label}:\n${loops.map((l) => mgr.formatLoop(l)).join("\n")}`,
+      "info",
+    );
+}
+
+function handleCancel(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const loopName = rest.trim();
+  if (!loopName) {
+    if (ctx.hasUI) ctx.ui.notify("Usage: /unipi:ralph cancel <name>", "warning");
+    return;
+  }
+
+  const mgr = getManager(ctx, pi);
+  const state = mgr.loadState(loopName);
+  if (!state) {
+    if (ctx.hasUI) ctx.ui.notify(`Loop "${loopName}" not found`, "error");
+    return;
+  }
+
+  if (mgr.getCurrentLoop() === loopName) mgr.setCurrentLoop(null);
+  const { tryDelete } = require("@pi-unipi/core");
+  tryDelete(
+    require("node:path").resolve(
+      ctx.cwd,
+      `.unipi/ralph/${loopName.replace(/[^a-zA-Z0-9_-]/g, "_")}.state.json`,
+    ),
+  );
+  if (ctx.hasUI) ctx.ui.notify(`Cancelled: ${loopName}`, "info");
+  mgr.updateUI();
+}
+
+function handleArchive(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const loopName = rest.trim();
+  if (!loopName) {
+    if (ctx.hasUI) ctx.ui.notify("Usage: /unipi:ralph archive <name>", "warning");
+    return;
+  }
+
+  const mgr = getManager(ctx, pi);
+  if (mgr.archiveLoop(loopName)) {
+    if (ctx.hasUI) ctx.ui.notify(`Archived: ${loopName}`, "info");
+  } else {
+    if (ctx.hasUI)
+      ctx.ui.notify(
+        `Cannot archive "${loopName}" — not found or still active`,
+        "warning",
+      );
+  }
+}
+
+function handleClean(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const mgr = getManager(ctx, pi);
+  const cleaned = mgr.cleanCompleted(rest.trim() === "--all");
+
+  if (cleaned.length === 0) {
+    if (ctx.hasUI) ctx.ui.notify("No completed loops to clean", "info");
+    return;
+  }
+
+  const suffix = rest.trim() === "--all" ? " (all files)" : " (state only)";
+  if (ctx.hasUI)
+    ctx.ui.notify(
+      `Cleaned ${cleaned.length} loop(s)${suffix}:\n${cleaned.map((n) => `  • ${n}`).join("\n")}`,
+      "info",
+    );
+}
+
+function handleNuke(
+  rest: string,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): void {
+  const force = rest.trim() === "--yes";
+
+  const run = () => {
+    const mgr = getManager(ctx, pi);
+    if (mgr.nukeAll()) {
+      if (ctx.hasUI) ctx.ui.notify("Removed .unipi/ralph directory.", "info");
+    } else {
+      if (ctx.hasUI) ctx.ui.notify("No .unipi/ralph directory found.", "info");
+    }
+  };
+
+  if (!force) {
+    if (ctx.hasUI) {
+      void ctx.ui
+        .confirm(
+          "Delete all Ralph loop files?",
+          "This deletes all .unipi/ralph state, task, and archive files.",
+        )
+        .then((confirmed) => {
+          if (confirmed) run();
+        });
+    } else {
+      if (ctx.hasUI)
+        ctx.ui.notify(
+          "Run /unipi:ralph nuke --yes to confirm. This deletes all .unipi/ralph data.",
+          "warning",
+        );
+    }
+    return;
+  }
+
+  run();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pi-unipi/ralph",
+  "version": "0.1.1",
+  "description": "Long-running iterative development loops for Pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/ralph"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "unipi",
+    "ralph",
+    "loops"
+  ],
+  "files": [
+    "*.ts",
+    "SKILL.md",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "^0.1.0",
+    "@pi-unipi/info-screen": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/ralph-loop.ts

@@ -0,0 +1,431 @@
+/**
+ * @unipi/ralph — Ralph loop state management
+ *
+ * Manages loop state, file I/O, and loop lifecycle.
+ * Adapted from pi-ralph-wiggum.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  RALPH_DIR,
+  RALPH_COMPLETE_MARKER,
+  RALPH_DEFAULTS,
+  RALPH_STATUS_ICONS,
+  UNIPI_EVENTS,
+  type UnipiRalphLoopEvent,
+  sanitize,
+  ensureDir,
+  tryDelete,
+  tryRead,
+  safeMtimeMs,
+  tryRemoveDir,
+  readJson,
+  writeJson,
+  now,
+} from "@pi-unipi/core";
+
+/** Loop status */
+export type LoopStatus = "active" | "paused" | "completed";
+
+/** Loop state persisted to disk */
+export interface LoopState {
+  name: string;
+  taskFile: string;
+  iteration: number;
+  maxIterations: number;
+  itemsPerIteration: number;
+  reflectEvery: number;
+  reflectInstructions: string;
+  active: boolean; // Backwards compat
+  status: LoopStatus;
+  startedAt: string;
+  completedAt?: string;
+  lastReflectionAt: number;
+}
+
+/** Default reflection instructions */
+export const DEFAULT_REFLECT_INSTRUCTIONS = `REFLECTION CHECKPOINT
+
+Pause and reflect on your progress:
+1. What has been accomplished so far?
+2. What's working well?
+3. What's not working or blocking progress?
+4. Should the approach be adjusted?
+5. What are the next priorities?
+
+Update the task file with your reflection, then continue working.`;
+
+/** Default task template */
+export const DEFAULT_TEMPLATE = `# Task
+
+Describe your task here.
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Checklist
+- [ ] Item 1
+- [ ] Item 2
+
+## Notes
+(Update this as you work)
+`;
+
+/** Ralph loop manager */
+export class RalphLoopManager {
+  private currentLoop: string | null = null;
+  private ctx: ExtensionContext;
+  private emitFn: (event: string, payload: unknown) => void;
+
+  constructor(ctx: ExtensionContext, emitFn: (event: string, payload: unknown) => void) {
+    this.ctx = ctx;
+    this.emitFn = emitFn;
+  }
+
+  // --- File helpers ---
+
+  private ralphDir(): string {
+    return path.resolve(this.ctx.cwd, RALPH_DIR);
+  }
+
+  private archiveDir(): string {
+    return path.join(this.ralphDir(), "archive");
+  }
+
+  private getPath(name: string, ext: string, archived = false): string {
+    const dir = archived ? this.archiveDir() : this.ralphDir();
+    return path.join(dir, `${sanitize(name)}${ext}`);
+  }
+
+  // --- State management ---
+
+  private migrateState(raw: Partial<LoopState> & { name: string }): LoopState {
+    if (!raw.status) raw.status = raw.active ? "active" : "paused";
+    raw.active = raw.status === "active";
+    return raw as LoopState;
+  }
+
+  loadState(name: string, archived = false): LoopState | null {
+    const content = tryRead(this.getPath(name, ".state.json", archived));
+    return content ? this.migrateState(JSON.parse(content)) : null;
+  }
+
+  saveState(state: LoopState, archived = false): void {
+    state.active = state.status === "active";
+    const filePath = this.getPath(state.name, ".state.json", archived);
+    ensureDir(filePath);
+    writeJson(filePath, state);
+  }
+
+  listLoops(archived = false): LoopState[] {
+    const dir = archived ? this.archiveDir() : this.ralphDir();
+    if (!fs.existsSync(dir)) return [];
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".state.json"))
+      .map((f) => {
+        const content = tryRead(path.join(dir, f));
+        return content ? this.migrateState(JSON.parse(content)) : null;
+      })
+      .filter((s): s is LoopState => s !== null);
+  }
+
+  // --- Loop state transitions ---
+
+  pauseLoop(state: LoopState, message?: string): void {
+    state.status = "paused";
+    state.active = false;
+    this.saveState(state);
+    this.currentLoop = null;
+    this.updateUI();
+    if (message && this.ctx.hasUI) this.ctx.ui.notify(message, "info");
+  }
+
+  completeLoop(state: LoopState, banner: string): void {
+    state.status = "completed";
+    state.completedAt = now();
+    state.active = false;
+    this.saveState(state);
+
+    // Emit event
+    this.emitFn(UNIPI_EVENTS.RALPH_LOOP_END, {
+      name: state.name,
+      iteration: state.iteration,
+      maxIterations: state.maxIterations,
+      status: "completed",
+      reason: "completed",
+    } satisfies UnipiRalphLoopEvent);
+
+    this.currentLoop = null;
+    this.updateUI();
+  }
+
+  stopLoop(state: LoopState, message?: string): void {
+    state.status = "completed";
+    state.completedAt = now();
+    state.active = false;
+    this.saveState(state);
+
+    // Emit event
+    this.emitFn(UNIPI_EVENTS.RALPH_LOOP_END, {
+      name: state.name,
+      iteration: state.iteration,
+      maxIterations: state.maxIterations,
+      status: "completed",
+      reason: "cancelled",
+    } satisfies UnipiRalphLoopEvent);
+
+    this.currentLoop = null;
+    this.updateUI();
+    if (message && this.ctx.hasUI) this.ctx.ui.notify(message, "info");
+  }
+
+  // --- UI ---
+
+  formatLoop(l: LoopState): string {
+    const status = `${RALPH_STATUS_ICONS[l.status]} ${l.status}`;
+    const iter = l.maxIterations > 0 ? `${l.iteration}/${l.maxIterations}` : `${l.iteration}`;
+    return `${l.name}: ${status} (iteration ${iter})`;
+  }
+
+  updateUI(): void {
+    if (!this.ctx.hasUI) return;
+
+    const state = this.currentLoop ? this.loadState(this.currentLoop) : null;
+    if (!state) {
+      this.ctx.ui.setStatus("ralph", undefined);
+      this.ctx.ui.setWidget("ralph", undefined);
+      return;
+    }
+
+    const { theme } = this.ctx.ui;
+    const maxStr = state.maxIterations > 0 ? `/${state.maxIterations}` : "";
+
+    this.ctx.ui.setStatus("ralph", theme.fg("accent", `🔄 ${state.name} (${state.iteration}${maxStr})`));
+
+    const lines = [
+      theme.fg("accent", theme.bold("Ralph Loop")),
+      theme.fg("muted", `Loop: ${state.name}`),
+      theme.fg("dim", `Status: ${RALPH_STATUS_ICONS[state.status]} ${state.status}`),
+      theme.fg("dim", `Iteration: ${state.iteration}${maxStr}`),
+      theme.fg("dim", `Task: ${state.taskFile}`),
+    ];
+    if (state.reflectEvery > 0) {
+      const next = state.reflectEvery - ((state.iteration - 1) % state.reflectEvery);
+      lines.push(theme.fg("dim", `Next reflection in: ${next} iterations`));
+    }
+    lines.push("");
+    lines.push(theme.fg("warning", "ESC pauses the assistant"));
+    lines.push(theme.fg("warning", "Send a message to resume; /unipi:ralph-stop ends the loop"));
+    this.ctx.ui.setWidget("ralph", lines);
+  }
+
+  // --- Prompt building ---
+
+  buildPrompt(state: LoopState, taskContent: string, isReflection: boolean): string {
+    const maxStr = state.maxIterations > 0 ? `/${state.maxIterations}` : "";
+    const header = `───────────────────────────────────────────────────────────────────────
+🔄 RALPH LOOP: ${state.name} | Iteration ${state.iteration}${maxStr}${isReflection ? " | 🪞 REFLECTION" : ""}
+───────────────────────────────────────────────────────────────────────`;
+
+    const parts = [header, ""];
+    if (isReflection) parts.push(state.reflectInstructions, "\n---\n");
+
+    parts.push(`## Current Task (from ${state.taskFile})\n\n${taskContent}\n\n---`);
+    parts.push(`\n## Instructions\n`);
+    parts.push("User controls: ESC pauses the assistant. Send a message to resume. Run /unipi:ralph-stop when idle to stop the loop.\n");
+    parts.push(
+      `You are in a Ralph loop (iteration ${state.iteration}${state.maxIterations > 0 ? ` of ${state.maxIterations}` : ""}).\n`,
+    );
+
+    if (state.itemsPerIteration > 0) {
+      parts.push(`**THIS ITERATION: Process approximately ${state.itemsPerIteration} items, then call ralph_done.**\n`);
+      parts.push(`1. Work on the next ~${state.itemsPerIteration} items from your checklist`);
+    } else {
+      parts.push(`1. Continue working on the task`);
+    }
+    parts.push(`2. Update the task file (${state.taskFile}) with your progress`);
+    parts.push(`3. When FULLY COMPLETE, respond with: ${RALPH_COMPLETE_MARKER}`);
+    parts.push(`4. Otherwise, call the ralph_done tool to proceed to next iteration`);
+
+    return parts.join("\n");
+  }
+
+  // --- Public API ---
+
+  getCurrentLoop(): string | null {
+    return this.currentLoop;
+  }
+
+  setCurrentLoop(name: string | null): void {
+    this.currentLoop = name;
+  }
+
+  getTaskFilePath(state: LoopState): string {
+    return path.resolve(this.ctx.cwd, state.taskFile);
+  }
+
+  tryReadTask(state: LoopState): string | null {
+    return tryRead(this.getTaskFilePath(state));
+  }
+
+  rehydrate(): void {
+    const active = this.listLoops().filter((l) => l.status === "active");
+    if (!this.currentLoop && active.length > 0) {
+      const mostRecent = active.reduce((best, candidate) => {
+        const bestMtime = safeMtimeMs(this.getPath(best.name, ".state.json"));
+        const candidateMtime = safeMtimeMs(this.getPath(candidate.name, ".state.json"));
+        return candidateMtime > bestMtime ? candidate : best;
+      });
+      this.currentLoop = mostRecent.name;
+    }
+
+    if (active.length > 0 && this.ctx.hasUI) {
+      const lines = active.map(
+        (l) => `  • ${l.name} (iteration ${l.iteration}${l.maxIterations > 0 ? `/${l.maxIterations}` : ""})`,
+      );
+      this.ctx.ui.notify(`Active Ralph loops:\n${lines.join("\n")}\n\nUse /unipi:ralph-resume <name> to continue`, "info");
+    }
+    this.updateUI();
+  }
+
+  // --- Loop operations ---
+
+  startLoop(name: string, taskFile: string, taskContent: string, options: {
+    maxIterations?: number;
+    itemsPerIteration?: number;
+    reflectEvery?: number;
+    reflectInstructions?: string;
+  } = {}): LoopState {
+    const loopName = sanitize(name);
+    const fullPath = path.resolve(this.ctx.cwd, taskFile);
+    ensureDir(fullPath);
+    fs.writeFileSync(fullPath, taskContent, "utf-8");
+
+    const state: LoopState = {
+      name: loopName,
+      taskFile,
+      iteration: 1,
+      maxIterations: options.maxIterations ?? RALPH_DEFAULTS.MAX_ITERATIONS,
+      itemsPerIteration: options.itemsPerIteration ?? RALPH_DEFAULTS.ITEMS_PER_ITERATION,
+      reflectEvery: options.reflectEvery ?? RALPH_DEFAULTS.REFLECT_EVERY,
+      reflectInstructions: options.reflectInstructions ?? DEFAULT_REFLECT_INSTRUCTIONS,
+      active: true,
+      status: "active",
+      startedAt: now(),
+      lastReflectionAt: 0,
+    };
+
+    this.saveState(state);
+    this.currentLoop = loopName;
+    this.updateUI();
+
+    // Emit event
+    this.emitFn(UNIPI_EVENTS.RALPH_LOOP_START, {
+      name: loopName,
+      iteration: 1,
+      maxIterations: state.maxIterations,
+      status: "active",
+    } satisfies UnipiRalphLoopEvent);
+
+    return state;
+  }
+
+  resumeLoop(name: string): LoopState | null {
+    const state = this.loadState(name);
+    if (!state) return null;
+    if (state.status === "completed") return null;
+
+    // Pause current loop if different
+    if (this.currentLoop && this.currentLoop !== name) {
+      const curr = this.loadState(this.currentLoop);
+      if (curr) this.pauseLoop(curr);
+    }
+
+    state.status = "active";
+    state.active = true;
+    state.iteration++;
+    this.saveState(state);
+    this.currentLoop = name;
+    this.updateUI();
+
+    return state;
+  }
+
+  advanceIteration(): { state: LoopState; needsReflection: boolean } | null {
+    if (!this.currentLoop) return null;
+
+    const state = this.loadState(this.currentLoop);
+    if (!state || state.status !== "active") return null;
+
+    state.iteration++;
+
+    // Check max iterations
+    if (state.maxIterations > 0 && state.iteration > state.maxIterations) {
+      this.completeLoop(
+        state,
+        `───────────────────────────────────────────────────────────────────────
+⚠️ RALPH LOOP STOPPED: ${state.name} | Max iterations (${state.maxIterations}) reached
+───────────────────────────────────────────────────────────────────────`,
+      );
+      return null;
+    }
+
+    const needsReflection =
+      state.reflectEvery > 0 && (state.iteration - 1) % state.reflectEvery === 0;
+    if (needsReflection) state.lastReflectionAt = state.iteration;
+
+    this.saveState(state);
+    this.updateUI();
+
+    return { state, needsReflection };
+  }
+
+  archiveLoop(name: string): boolean {
+    const state = this.loadState(name);
+    if (!state) return false;
+    if (state.status === "active") return false;
+
+    if (this.currentLoop === name) this.currentLoop = null;
+
+    const srcState = this.getPath(name, ".state.json");
+    const dstState = this.getPath(name, ".state.json", true);
+    ensureDir(dstState);
+    if (fs.existsSync(srcState)) fs.renameSync(srcState, dstState);
+
+    const srcTask = path.resolve(this.ctx.cwd, state.taskFile);
+    if (srcTask.startsWith(this.ralphDir()) && !srcTask.startsWith(this.archiveDir())) {
+      const dstTask = this.getPath(name, ".md", true);
+      if (fs.existsSync(srcTask)) fs.renameSync(srcTask, dstTask);
+    }
+
+    this.updateUI();
+    return true;
+  }
+
+  cleanCompleted(all = false): string[] {
+    const completed = this.listLoops().filter((l) => l.status === "completed");
+    const cleaned: string[] = [];
+
+    for (const loop of completed) {
+      tryDelete(this.getPath(loop.name, ".state.json"));
+      if (all) tryDelete(this.getPath(loop.name, ".md"));
+      if (this.currentLoop === loop.name) this.currentLoop = null;
+      cleaned.push(loop.name);
+    }
+
+    this.updateUI();
+    return cleaned;
+  }
+
+  nukeAll(): boolean {
+    const dir = this.ralphDir();
+    if (!fs.existsSync(dir)) return false;
+    this.currentLoop = null;
+    this.updateUI();
+    return tryRemoveDir(dir);
+  }
+}

package/tools.ts

@@ -0,0 +1,156 @@
+/**
+ * @unipi/ralph — Ralph tools (ralph_start, ralph_done)
+ *
+ * Tools for the LLM to control ralph loops.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { RALPH_COMPLETE_MARKER, RALPH_DEFAULTS, RALPH_TOOLS } from "@pi-unipi/core";
+import { RalphLoopManager, DEFAULT_REFLECT_INSTRUCTIONS } from "./ralph-loop.js";
+
+/**
+ * Register ralph_start and ralph_done tools.
+ */
+export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager): void {
+  // --- ralph_start tool ---
+  pi.registerTool({
+    name: RALPH_TOOLS.START,
+    label: "Start Ralph Loop",
+    description:
+      "Start a long-running development loop. Use for complex multi-iteration tasks.",
+    promptSnippet:
+      "Start a persistent multi-iteration development loop with pacing and reflection controls.",
+    promptGuidelines: [
+      "Use ralph_start when the user explicitly wants an iterative loop, autonomous repeated passes, or paced multi-step execution.",
+      "After starting a loop, continue each finished iteration with ralph_done unless the completion marker has already been emitted.",
+    ],
+    parameters: Type.Object({
+      name: Type.String({ description: "Loop name (e.g., 'refactor-auth')" }),
+      taskContent: Type.String({
+        description: "Task in markdown with goals and checklist",
+      }),
+      itemsPerIteration: Type.Optional(
+        Type.Number({ description: "Suggest N items per turn (0 = no limit)" }),
+      ),
+      reflectEvery: Type.Optional(
+        Type.Number({ description: "Reflect every N iterations" }),
+      ),
+      maxIterations: Type.Optional(
+        Type.Number({
+          description: "Max iterations (default: 50)",
+          default: RALPH_DEFAULTS.MAX_ITERATIONS,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const taskFile = `.unipi/ralph/${params.name.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`;
+
+      if (manager.loadState(params.name)?.status === "active") {
+        return {
+          content: [
+            { type: "text", text: `Loop "${params.name}" already active.` },
+          ],
+          details: {},
+        };
+      }
+
+      const state = manager.startLoop(params.name, taskFile, params.taskContent, {
+        maxIterations: params.maxIterations,
+        itemsPerIteration: params.itemsPerIteration,
+        reflectEvery: params.reflectEvery,
+      });
+
+      pi.sendUserMessage(
+        manager.buildPrompt(state, params.taskContent, false),
+        { deliverAs: "followUp" },
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Started loop "${params.name}" (max ${state.maxIterations} iterations).`,
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+
+  // --- ralph_done tool ---
+  pi.registerTool({
+    name: RALPH_TOOLS.DONE,
+    label: "Ralph Iteration Done",
+    description:
+      "Signal that you've completed this iteration of the Ralph loop. Call this after making progress to get the next iteration prompt. Do NOT call this if you've output the completion marker.",
+    promptSnippet:
+      "Advance an active Ralph loop after completing the current iteration.",
+    promptGuidelines: [
+      "Call ralph_done after making real iteration progress so Ralph can queue the next prompt.",
+      "Do not call ralph_done if there is no active loop, if pending messages are already queued, or if the completion marker has already been emitted.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      if (!manager.getCurrentLoop()) {
+        return {
+          content: [{ type: "text", text: "No active Ralph loop." }],
+          details: {},
+        };
+      }
+
+      if (ctx.hasPendingMessages()) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Pending messages already queued. Skipping ralph_done.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      const result = manager.advanceIteration();
+      if (!result) {
+        return {
+          content: [
+            { type: "text", text: "Ralph loop completed or not active." },
+          ],
+          details: {},
+        };
+      }
+
+      const { state, needsReflection } = result;
+      const content = manager.tryReadTask(state);
+      if (!content) {
+        manager.pauseLoop(state);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: Could not read task file: ${state.taskFile}`,
+            },
+          ],
+          details: {},
+        };
+      }
+
+      // Queue next iteration
+      pi.sendUserMessage(
+        manager.buildPrompt(state, content, needsReflection),
+        { deliverAs: "followUp" },
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Iteration ${state.iteration - 1} complete. Next iteration queued.`,
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}