@lnilluv/pi-ralph-loop 0.0.1

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - dev
+  pull_request:
+
+permissions: read-all
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Setup Node.js 22
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Typecheck
+        run: npm run typecheck

package/.github/workflows/release.yml

@@ -0,0 +1,150 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js 22
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Determine version bump
+        id: bump
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          last_tag="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+          if [ -n "$last_tag" ]; then
+            range="${last_tag}..HEAD"
+          else
+            range="HEAD"
+          fi
+
+          subjects="$(git log --format=%s $range)"
+          bodies="$(git log --format=%b $range)"
+
+          bump=""
+          if echo "$subjects" | grep -Eq '^(feat|fix)!:' || echo "$bodies" | grep -q 'BREAKING CHANGE'; then
+            bump="major"
+          elif echo "$subjects" | grep -Eq '^feat(\(.+\))?:'; then
+            bump="minor"
+          elif echo "$subjects" | grep -Eq '^fix(\(.+\))?:'; then
+            bump="patch"
+          fi
+
+          if [ -z "$bump" ]; then
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            echo "No feat/fix commits found since ${last_tag:-repository start}; skipping release."
+            exit 0
+          fi
+
+          branch="${GITHUB_REF_NAME}"
+          current_version="$(node -p "require('./package.json').version")"
+          new_version="$(node - "$current_version" "$branch" "$bump" <<'NODE'
+          const [current, branch, bump] = process.argv.slice(2);
+          const match = current.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+          if (!match) throw new Error(`Unsupported version: ${current}`);
+
+          let major = Number(match[1]);
+          let minor = Number(match[2]);
+          let patch = Number(match[3]);
+          const prerelease = match[4];
+
+          if (branch === 'dev') {
+            if (prerelease && prerelease.startsWith('dev.')) {
+              const currentN = Number(prerelease.split('.')[1] ?? '0');
+              process.stdout.write(`${major}.${minor}.${patch}-dev.${currentN + 1}`);
+            } else {
+              if (bump === 'major') { major += 1; minor = 0; patch = 0; }
+              else if (bump === 'minor') { minor += 1; patch = 0; }
+              else { patch += 1; }
+              process.stdout.write(`${major}.${minor}.${patch}-dev.0`);
+            }
+          } else {
+            if (bump === 'major') { major += 1; minor = 0; patch = 0; }
+            else if (bump === 'minor') { minor += 1; patch = 0; }
+            else { patch += 1; }
+            process.stdout.write(`${major}.${minor}.${patch}`);
+          }
+          NODE
+          )"
+
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+          echo "bump=$bump" >> "$GITHUB_OUTPUT"
+          echo "new_version=$new_version" >> "$GITHUB_OUTPUT"
+
+      - name: Bump version (main)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
+        run: npm version ${{ steps.bump.outputs.bump }} --no-git-tag-version
+
+      - name: Bump version (dev)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'dev'
+        run: npm version prerelease --preid dev --no-git-tag-version
+
+      - name: Capture version tag
+        if: steps.bump.outputs.should_release == 'true'
+        id: version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Publish (main)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
+        run: npx npm@11 publish --access public --provenance
+
+      - name: Publish (dev prerelease)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'dev'
+        run: npx npm@11 publish --access public --provenance --tag dev
+
+      - name: Commit version bump and tag
+        if: steps.bump.outputs.should_release == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION=$(node -p "require('./package.json').version")
+          git add package.json package-lock.json
+          git commit -m "chore(release): v${VERSION}"
+          git tag "v${VERSION}"
+          git push
+          git push --tags
+
+      - name: Create GitHub Release (main)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
+        run: gh release create "${{ steps.version.outputs.tag }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Create GitHub Release (dev prerelease)
+        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'dev'
+        run: gh release create "${{ steps.version.outputs.tag }}" --prerelease --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

package/README.md

@@ -0,0 +1,106 @@
+# pi-ralph
+
+Autonomous coding loops for pi with mid-turn supervision.
+
+## Install
+
+```bash
+pi install npm:@lnilluv/pi-ralph-loop
+```
+
+## Quick start
+
+```md
+# my-task/RALPH.md
+---
+commands:
+  - name: tests
+    run: npm test -- --runInBand
+    timeout: 60
+---
+Fix failing tests using this output:
+
+{{ commands.tests }}
+```
+
+Run `/ralph my-task` in pi.
+
+## How it works
+
+On each iteration, pi-ralph reads `RALPH.md`, runs the configured commands, injects their output into the prompt through `{{ commands.<name> }}` placeholders, starts a fresh session, sends the prompt, and waits for completion. Failed test output appears in the next iteration, which creates a self-healing loop.
+
+## RALPH.md format
+
+```md
+---
+commands:
+  - name: tests
+    run: npm test -- --runInBand
+    timeout: 90
+  - name: lint
+    run: npm run lint
+    timeout: 60
+max_iterations: 25
+guardrails:
+  block_commands:
+    - "rm\\s+-rf\\s+/"
+    - "git\\s+push"
+  protected_files:
+    - ".env*"
+    - "**/secrets/**"
+---
+You are fixing flaky tests in the auth module.
+
+Latest test output:
+{{ commands.tests }}
+
+Latest lint output:
+{{ commands.lint }}
+
+Apply the smallest safe fix and explain why it works.
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `commands` | array | `[]` | Commands to run each iteration |
+| `commands[].name` | string | required | Key for `{{ commands.<name> }}` |
+| `commands[].run` | string | required | Shell command |
+| `commands[].timeout` | number | `60` | Seconds before kill |
+| `max_iterations` | number | `50` | Stop after N iterations |
+| `guardrails.block_commands` | string[] | `[]` | Regex patterns to block in bash |
+| `guardrails.protected_files` | string[] | `[]` | Glob patterns to block writes |
+
+## Commands
+
+- `/ralph <path>`: Start the loop from a `RALPH.md` file or directory.
+- `/ralph-stop`: Request a graceful stop after the current iteration.
+
+## Pi-only features
+
+### Guardrails
+
+`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook. Matching bash commands are blocked, and writes/edits to protected file globs are denied.
+
+### Cross-iteration memory
+
+After each iteration, the extension stores a short summary with iteration number and duration. In `before_agent_start`, it injects that history into the system prompt so the next run can avoid repeating completed work.
+
+### Mid-turn steering
+
+In the `tool_result` hook, bash outputs are scanned for failure patterns. After three or more failures in the same iteration, the extension appends a stop-and-think warning to push root-cause analysis before another retry.
+
+## Comparison table
+
+| Feature | **@lnilluv/pi-ralph-loop** | pi-ralph | pi-ralph-wiggum | ralphi | ralphify |
+|---------|------------------------|----------------------|-----------------|--------|----------|
+| Command output injection | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Fresh-context sessions | ✓ | ✓ | ✗ | ✓ | ✓ |
+| Mid-turn guardrails | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Cross-iteration memory | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Mid-turn steering | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Live prompt editing | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Setup required | RALPH.md | config | RALPH.md | PRD pipeline | RALPH.md |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@lnilluv/pi-ralph-loop",
+  "version": "0.0.1",
+  "description": "Pi-native ralph loop — autonomous coding iterations with mid-turn supervision",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lnilluv/pi-ralph-loop.git"
+  },
+  "dependencies": {
+    "yaml": "2.7.1",
+    "minimatch": "10.0.1"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "keywords": [
+    "pi-extension",
+    "ralph",
+    "autonomous",
+    "loop"
+  ],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,271 @@
+import { parse as parseYaml } from "yaml";
+import { minimatch } from "minimatch";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, dirname, basename } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// --- Types ---
+
+type CommandDef = { name: string; run: string; timeout: number };
+
+type Frontmatter = {
+  commands: CommandDef[];
+  maxIterations: number;
+  guardrails: { blockCommands: string[]; protectedFiles: string[] };
+};
+
+type ParsedRalph = { frontmatter: Frontmatter; body: string };
+type CommandOutput = { name: string; output: string };
+
+type LoopState = {
+  active: boolean;
+  ralphPath: string;
+  iteration: number;
+  maxIterations: number;
+  stopRequested: boolean;
+  failCount: number;
+  iterationSummaries: Array<{ iteration: number; duration: number }>;
+  guardrails: { blockCommands: RegExp[]; protectedFiles: string[] };
+};
+
+// --- Parsing ---
+
+function defaultFrontmatter(): Frontmatter {
+  return { commands: [], maxIterations: 50, guardrails: { blockCommands: [], protectedFiles: [] } };
+}
+
+function parseRalphMd(filePath: string): ParsedRalph {
+  const raw = readFileSync(filePath, "utf8");
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: defaultFrontmatter(), body: raw };
+
+  const yaml = parseYaml(match[1]) ?? {};
+  const commands: CommandDef[] = Array.isArray(yaml.commands)
+    ? yaml.commands.map((c: Record<string, unknown>) => ({
+        name: String(c.name ?? ""),
+        run: String(c.run ?? ""),
+        timeout: Number(c.timeout ?? 60),
+      }))
+    : [];
+
+  const guardrails = yaml.guardrails ?? {};
+  return {
+    frontmatter: {
+      commands,
+      maxIterations: Number(yaml.max_iterations ?? 50),
+      guardrails: {
+        blockCommands: Array.isArray(guardrails.block_commands) ? guardrails.block_commands : [],
+        protectedFiles: Array.isArray(guardrails.protected_files) ? guardrails.protected_files : [],
+      },
+    },
+    body: match[2],
+  };
+}
+
+function resolveRalphPath(args: string, cwd: string): string {
+  const target = args.trim() || ".";
+  const abs = resolve(cwd, target);
+  if (existsSync(abs) && abs.endsWith(".md")) return abs;
+  if (existsSync(join(abs, "RALPH.md"))) return join(abs, "RALPH.md");
+  throw new Error(`No RALPH.md found at ${abs}`);
+}
+
+function resolvePlaceholders(body: string, outputs: CommandOutput[]): string {
+  const map = new Map(outputs.map((o) => [o.name, o.output]));
+  return body.replace(/\{\{\s*commands\.(\w[\w-]*)\s*\}\}/g, (_, name) => map.get(name) ?? "");
+}
+
+function parseGuardrails(fm: Frontmatter): LoopState["guardrails"] {
+  return {
+    blockCommands: fm.guardrails.blockCommands.map((p) => new RegExp(p)),
+    protectedFiles: fm.guardrails.protectedFiles,
+  };
+}
+
+// --- Command execution ---
+
+async function runCommands(
+  commands: CommandDef[],
+  cwd: string,
+  pi: ExtensionAPI,
+): Promise<CommandOutput[]> {
+  const results: CommandOutput[] = [];
+  for (const cmd of commands) {
+    try {
+      const result = await pi.exec("bash", ["-c", cmd.run], { timeout: cmd.timeout * 1000 });
+      results.push({
+        name: cmd.name,
+        output: (result.stdout + result.stderr).trim(),
+      });
+    } catch {
+      results.push({ name: cmd.name, output: `[timed out after ${cmd.timeout}s]` });
+    }
+  }
+  return results;
+}
+
+// --- Extension ---
+
+let loopState: LoopState = {
+  active: false,
+  ralphPath: "",
+  iteration: 0,
+  maxIterations: 50,
+  stopRequested: false,
+  failCount: 0,
+  iterationSummaries: [],
+  guardrails: { blockCommands: [], protectedFiles: [] },
+};
+
+export default function (pi: ExtensionAPI) {
+  // Guardrails: block dangerous tool calls during loop
+  pi.on("tool_call", async (event) => {
+    if (!loopState.active) return;
+
+    if (event.toolName === "bash") {
+      const cmd = (event.input as { command?: string }).command ?? "";
+      for (const pattern of loopState.guardrails.blockCommands) {
+        if (pattern.test(cmd)) {
+          return { block: true, reason: `ralph: blocked (${pattern.source})` };
+        }
+      }
+    }
+
+    if (event.toolName === "write" || event.toolName === "edit") {
+      const filePath = (event.input as { path?: string }).path ?? "";
+      for (const glob of loopState.guardrails.protectedFiles) {
+        if (minimatch(filePath, glob, { matchBase: true })) {
+          return { block: true, reason: `ralph: ${filePath} is protected` };
+        }
+      }
+    }
+  });
+
+  // Cross-iteration memory: inject context into system prompt
+  pi.on("before_agent_start", async (event) => {
+    if (!loopState.active || loopState.iterationSummaries.length === 0) return;
+
+    const history = loopState.iterationSummaries
+      .map((s) => `- Iteration ${s.iteration}: ${s.duration}s`)
+      .join("\n");
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `\n\n## Ralph Loop Context\nIteration ${loopState.iteration}/${loopState.maxIterations}\n\nPrevious iterations:\n${history}\n\nDo not repeat completed work. Check git log for recent changes.`,
+    };
+  });
+
+  // Mid-turn steering: warn after repeated failures
+  pi.on("tool_result", async (event) => {
+    if (!loopState.active || event.toolName !== "bash") return;
+
+    const output = event.content
+      .map((c: { type: string; text?: string }) => (c.type === "text" ? c.text ?? "" : ""))
+      .join("");
+
+    if (/FAIL|ERROR|error:|failed/i.test(output)) {
+      loopState.failCount++;
+    }
+
+    if (loopState.failCount >= 3) {
+      return {
+        content: [
+          ...event.content,
+          {
+            type: "text" as const,
+            text: "\n\n⚠️ ralph: 3+ failures this iteration. Stop and describe the root cause before retrying.",
+          },
+        ],
+      };
+    }
+  });
+
+  // /ralph command: start the loop
+  pi.registerCommand("ralph", {
+    description: "Start an autonomous ralph loop from a RALPH.md file",
+    handler: async (args, ctx) => {
+      if (loopState.active) {
+        ctx.ui.notify("A ralph loop is already running. Use /ralph-stop first.", "warning");
+        return;
+      }
+
+      let ralphPath: string;
+      try {
+        ralphPath = resolveRalphPath(args ?? "", ctx.cwd);
+      } catch (err) {
+        ctx.ui.notify(String(err), "error");
+        return;
+      }
+
+      const { frontmatter } = parseRalphMd(ralphPath);
+      loopState = {
+        active: true,
+        ralphPath,
+        iteration: 0,
+        maxIterations: frontmatter.maxIterations,
+        stopRequested: false,
+        failCount: 0,
+        iterationSummaries: [],
+        guardrails: parseGuardrails(frontmatter),
+      };
+
+      const name = basename(dirname(ralphPath));
+      ctx.ui.notify(`Ralph loop started: ${name} (max ${loopState.maxIterations} iterations)`, "info");
+
+      for (let i = 1; i <= loopState.maxIterations; i++) {
+        if (loopState.stopRequested) break;
+
+        loopState.iteration = i;
+        loopState.failCount = 0;
+        const iterStart = Date.now();
+
+        // Re-parse every iteration (live editing support)
+        const { frontmatter: fm, body } = parseRalphMd(loopState.ralphPath);
+        loopState.maxIterations = fm.maxIterations;
+        loopState.guardrails = parseGuardrails(fm);
+
+        // Run commands and resolve placeholders
+        const outputs = await runCommands(fm.commands, ctx.cwd, pi);
+        const header = `[ralph: iteration ${i}/${loopState.maxIterations}]\n\n`;
+        const prompt = header + resolvePlaceholders(body, outputs);
+
+        // Fresh session
+        ctx.ui.setStatus("ralph", `🔁 ${name}: iteration ${i}/${loopState.maxIterations}`);
+        await ctx.newSession();
+
+        // Send prompt and wait for agent to finish
+        pi.sendUserMessage(prompt);
+        await ctx.waitForIdle();
+
+        // Record iteration
+        const elapsed = Math.round((Date.now() - iterStart) / 1000);
+        loopState.iterationSummaries.push({ iteration: i, duration: elapsed });
+        pi.appendEntry("ralph-iteration", { iteration: i, duration: elapsed, ralphPath: loopState.ralphPath });
+
+        ctx.ui.notify(`Iteration ${i} complete (${elapsed}s)`, "info");
+      }
+
+      loopState.active = false;
+      ctx.ui.setStatus("ralph", undefined);
+      const total = loopState.iterationSummaries.reduce((a, s) => a + s.duration, 0);
+      ctx.ui.notify(
+        `Ralph loop done: ${loopState.iteration} iterations, ${total}s total`,
+        "success",
+      );
+    },
+  });
+
+  // /ralph-stop command: graceful stop
+  pi.registerCommand("ralph-stop", {
+    description: "Stop the ralph loop after the current iteration",
+    handler: async (_args, ctx) => {
+      if (!loopState.active) {
+        ctx.ui.notify("No active ralph loop", "warning");
+        return;
+      }
+      loopState.stopRequested = true;
+      ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
+    },
+  });
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}