@lnilluv/pi-ralph-loop 1.0.0 → 1.2.0

package/tests/ralph.test.ts

@@ -121,6 +121,7 @@ test("parseRalphMarkdown parses frontmatter and normalizes line endings", () =>
     timeout: 12.5,
     completionPromise: "done",
     requiredOutputs: ["docs/ARCHITECTURE.md"],
+    stopOnError: true,
     guardrails: { blockCommands: ["rm .*"], protectedFiles: ["src/**"] },
     invalidCommandEntries: undefined,
   });
@@ -136,6 +137,21 @@ test("parseRalphMarkdown parses declared args as runtime parameters", () => {
   assert.equal(validateFrontmatter(parsed.frontmatter), null);
 });
 
+test("parseRalphMarkdown parses stop_on_error from frontmatter", () => {
+  const parsed = parseRalphMarkdown("---\nstop_on_error: false\nmax_iterations: 5\ntimeout: 60\ncommands: []\nguardrails: { block_commands: [], protected_files: [] }\n---\nTask\n");
+  assert.equal(parsed.frontmatter.stopOnError, false);
+});
+
+test("parseRalphMarkdown defaults stop_on_error to true", () => {
+  const parsed = parseRalphMarkdown("---\nmax_iterations: 5\ntimeout: 60\ncommands: []\nguardrails: { block_commands: [], protected_files: [] }\n---\nTask\n");
+  assert.equal(parsed.frontmatter.stopOnError, true);
+});
+
+test("parseRalphMarkdown treats non-false stop_on_error as true (safe default)", () => {
+  const parsed = parseRalphMarkdown("---\nstop_on_error: yes\nmax_iterations: 5\ntimeout: 60\ncommands: []\nguardrails: { block_commands: [], protected_files: [] }\n---\nTask\n");
+  assert.equal(parsed.frontmatter.stopOnError, true);
+});
+
 test("validateFrontmatter accepts valid input and rejects invalid bounds, names, args, and globs", () => {
   assert.equal(validateFrontmatter(defaultFrontmatter()), null);
   assert.equal(
@@ -244,6 +260,13 @@ test("validateFrontmatter accepts valid input and rejects invalid bounds, names,
   );
 });
 
+test("validateFrontmatter accepts stop_on_error true and false", () => {
+  const fmTrue = { ...defaultFrontmatter(), stopOnError: true };
+  const fmFalse = { ...defaultFrontmatter(), stopOnError: false };
+  assert.equal(validateFrontmatter(fmTrue), null);
+  assert.equal(validateFrontmatter(fmFalse), null);
+});
+
 test("validateFrontmatter rejects unsafe completion_promise values and Mission Brief fails closed", () => {
   assert.equal(
     validateFrontmatter({ ...defaultFrontmatter(), completionPromise: "ready\nnow" }),
@@ -1010,6 +1033,7 @@ test("generated drafts reparse as valid RALPH files", () => {
     timeout: 300,
     completionPromise: undefined,
     requiredOutputs: [],
+    stopOnError: true,
     guardrails: { blockCommands: ["git\\s+push"], protectedFiles: [] },
     invalidCommandEntries: undefined,
   });

package/tests/runner-event-contract.test.ts

@@ -36,7 +36,7 @@ type ExpectedRunnerEvent =
       timestamp: string;
       iteration: number;
       loopToken: string;
-      status: "complete" | "timeout" | "error";
+      status: "complete" | "timeout" | "error" | "cancelled";
       progress: ProgressState;
       changedFiles: string[];
       noProgressStreak: number;

package/tests/runner-rpc.test.ts

@@ -355,4 +355,92 @@ echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"te
   } finally {
     rmSync(cwd, { recursive: true, force: true });
   }
-});
+});
+
+
+test("runRpcIteration cancels on AbortSignal and returns cancelled=true", async () => {
+  const taskDir = mkdtempSync(join(tmpdir(), "pi-ralph-rpc-"));
+  try {
+    const scriptPath = join(taskDir, "slow-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+sleep 30
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"done"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+
+    const result = await runRpcIteration({
+      prompt: "do something",
+      cwd: taskDir,
+      timeoutMs: 60_000,
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      signal: controller.signal,
+    });
+
+    assert.equal(result.cancelled, true);
+    assert.equal(result.success, false);
+    assert.equal(result.timedOut, false);
+    assert.equal(result.error, "cancelled");
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("runRpcIteration returns immediately if AbortSignal is already aborted", async () => {
+  const taskDir = mkdtempSync(join(tmpdir(), "pi-ralph-rpc-"));
+  try {
+    const controller = new AbortController();
+    controller.abort();
+
+    const result = await runRpcIteration({
+      prompt: "do something",
+      cwd: taskDir,
+      timeoutMs: 5_000,
+      spawnCommand: "echo",
+      spawnArgs: ["mock"],
+      signal: controller.signal,
+    });
+
+    assert.equal(result.cancelled, true);
+    assert.equal(result.success, false);
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("runRpcIteration completes normally without AbortSignal", async () => {
+  const taskDir = mkdtempSync(join(tmpdir(), "pi-ralph-rpc-"));
+  try {
+    const scriptPath = join(taskDir, "fast-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"done"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    const result = await runRpcIteration({
+      prompt: "do something",
+      cwd: taskDir,
+      timeoutMs: 5_000,
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+    });
+
+    assert.equal(result.success, true);
+    assert.equal(result.cancelled, undefined);
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});

package/tests/runner-state.test.ts

@@ -11,9 +11,12 @@ import {
   type RunnerStatusFile,
   appendIterationRecord,
   appendRunnerEvent,
+  checkCancelSignal,
   checkStopSignal,
+  clearCancelSignal,
   clearRunnerDir,
   clearStopSignal,
+  createCancelSignal,
   createStopSignal,
   ensureRunnerDir,
   listActiveLoopRegistryEntries,
@@ -288,6 +291,31 @@ test("clearStopSignal is idempotent when no signal exists", () => {
   }
 });
 
+test("createCancelSignal writes cancel.flag and checkCancelSignal detects it", () => {
+  const taskDir = createTempDir();
+  try {
+    ensureRunnerDir(taskDir);
+    assert.equal(checkCancelSignal(taskDir), false);
+    createCancelSignal(taskDir);
+    assert.equal(checkCancelSignal(taskDir), true);
+    clearCancelSignal(taskDir);
+    assert.equal(checkCancelSignal(taskDir), false);
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("clearCancelSignal is safe when cancel.flag does not exist", () => {
+  const taskDir = createTempDir();
+  try {
+    ensureRunnerDir(taskDir);
+    clearCancelSignal(taskDir); // should not throw
+    assert.equal(checkCancelSignal(taskDir), false);
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
 // --- clearRunnerDir ---
 
 test("clearRunnerDir removes .ralph-runner directory", () => {

package/tests/runner.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import test from "node:test";
 
 import { assessTaskDirectoryProgress, captureTaskDirectorySnapshot, runRalphLoop, validateCompletionReadiness } from "../src/runner.ts";
-import { readStatusFile, readIterationRecords, readRunnerEvents, checkStopSignal, createStopSignal as createStopSignalFn, type RunnerEvent } from "../src/runner-state.ts";
+import { readStatusFile, readIterationRecords, readRunnerEvents, checkStopSignal, createCancelSignal, createStopSignal as createStopSignalFn, type RunnerEvent } from "../src/runner-state.ts";
 import { generateDraft } from "../src/ralph.ts";
 import type { DraftTarget, CommandOutput, CommandDef } from "../src/ralph.ts";
 
@@ -339,6 +339,86 @@ echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"te
   }
 });
 
+test("runRalphLoop cancels mid-iteration when cancel flag is written", async () => {
+  const taskDir = createTempDir();
+  try {
+    const ralphPath = writeRalphMd(taskDir, minimalRalphMd({ max_iterations: 3 }));
+
+    const scriptPath = join(taskDir, "slow-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+sleep 10
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"done"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    setTimeout(() => createCancelSignal(taskDir), 1000);
+
+    const result = await runRalphLoop({
+      ralphPath,
+      cwd: taskDir,
+      timeout: 30,
+      maxIterations: 3,
+      guardrails: { blockCommands: [], protectedFiles: [] },
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      runCommandsFn: async () => [],
+      pi: makeMockPi(),
+    });
+
+    assert.equal(result.status, "cancelled");
+    assert.ok(result.iterations.length >= 1);
+    assert.equal(result.iterations[result.iterations.length - 1].status, "cancelled");
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("runRalphLoop checks cancel flag at iteration boundary", async () => {
+  const taskDir = createTempDir();
+  try {
+    const ralphPath = writeRalphMd(taskDir, minimalRalphMd({ max_iterations: 3 }));
+
+    const scriptPath = join(taskDir, "mock-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"done"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    let iterationCount = 0;
+    const result = await runRalphLoop({
+      ralphPath,
+      cwd: taskDir,
+      timeout: 5,
+      maxIterations: 3,
+      guardrails: { blockCommands: [], protectedFiles: [] },
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      onIterationComplete() {
+        iterationCount++;
+        if (iterationCount >= 1) {
+          createCancelSignal(taskDir);
+        }
+      },
+      runCommandsFn: async () => [],
+      pi: makeMockPi(),
+    });
+
+    assert.equal(result.status, "cancelled");
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
 test("runRalphLoop waits between iterations when inter_iteration_delay is set", async () => {
   const taskDir = createTempDir();
   try {
@@ -1345,3 +1425,128 @@ echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"te
     rmSync(taskDir, { recursive: true, force: true });
   }
 });
+
+test("runRalphLoop stops on error when stopOnError is true (default)", async () => {
+  const taskDir = createTempDir();
+  try {
+    const ralphPath = writeRalphMd(taskDir, minimalRalphMd({ max_iterations: 3 }));
+
+    const scriptPath = join(taskDir, "failing-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+exit 1
+`,
+      { mode: 0o755 },
+    );
+
+    const result = await runRalphLoop({
+      ralphPath,
+      cwd: taskDir,
+      timeout: 5,
+      maxIterations: 3,
+      stopOnError: true,
+      guardrails: { blockCommands: [], protectedFiles: [] },
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      runCommandsFn: async () => [],
+      pi: makeMockPi(),
+    });
+
+    assert.equal(result.status, "error");
+    assert.equal(result.iterations.length, 1);
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("runRalphLoop continues past error when stopOnError is false", async () => {
+  const taskDir = createTempDir();
+  try {
+    const ralphPath = writeRalphMd(taskDir, minimalRalphMd({ max_iterations: 3 }));
+
+    const scriptPath = join(taskDir, "maybe-fail-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+COUNTER_FILE="${taskDir}/.call-counter"
+COUNT=0
+if [ -f "$COUNTER_FILE" ]; then
+  COUNT=$(cat "$COUNTER_FILE")
+fi
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+echo '{"type":"response","command":"prompt","success":true}'
+if [ "$COUNT" -le 1 ]; then
+  exit 1
+fi
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"done"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    const result = await runRalphLoop({
+      ralphPath,
+      cwd: taskDir,
+      timeout: 5,
+      maxIterations: 3,
+      stopOnError: false,
+      guardrails: { blockCommands: [], protectedFiles: [] },
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      runCommandsFn: async () => [],
+      pi: makeMockPi(),
+    });
+
+    assert.ok(result.iterations.length > 1, `Expected >1 iteration, got ${result.iterations.length}`);
+    assert.equal(result.iterations[0].status, "error");
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+
+test("runRalphLoop breaks on structural failure even with stopOnError false", async () => {
+  const taskDir = createTempDir();
+  try {
+    const ralphPath = writeRalphMd(taskDir, minimalRalphMd({ max_iterations: 3, stop_on_error: false }));
+
+    const scriptPath = join(taskDir, "mock-pi.sh");
+    writeFileSync(
+      scriptPath,
+      `#!/bin/bash
+read line
+echo '{"type":"response","command":"prompt","success":true}'
+echo '{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"delete ralph"}]}]}'
+`,
+      { mode: 0o755 },
+    );
+
+    let iterationCount = 0;
+    const result = await runRalphLoop({
+      ralphPath,
+      cwd: taskDir,
+      timeout: 5,
+      maxIterations: 3,
+      stopOnError: false,
+      guardrails: { blockCommands: [], protectedFiles: [] },
+      spawnCommand: "bash",
+      spawnArgs: [scriptPath],
+      onIterationComplete() {
+        iterationCount++;
+        if (iterationCount >= 1) {
+          rmSync(ralphPath, { force: true });
+        }
+      },
+      runCommandsFn: async () => [],
+      pi: makeMockPi(),
+    });
+
+    assert.equal(result.status, "error");
+  } finally {
+    rmSync(taskDir, { recursive: true, force: true });
+  }
+});
+