ralph-mcp 1.1.0 → 1.1.1

package/dist/index.js

@@ -10,6 +10,8 @@ import { update, updateInputSchema } from "./tools/update.js";
 import { stop, stopInputSchema } from "./tools/stop.js";
 import { merge, mergeInputSchema, mergeQueueAction, mergeQueueInputSchema } from "./tools/merge.js";
 import { setAgentId, setAgentIdInputSchema } from "./tools/set-agent-id.js";
+import { resetStagnationTool, resetStagnationInputSchema } from "./tools/reset-stagnation.js";
+import { retry, retryInputSchema } from "./tools/retry.js";
 const server = new Server({
     name: "ralph",
     version: "1.0.0",
@@ -120,6 +122,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Implementation notes",
                         },
+                        filesChanged: {
+                            type: "number",
+                            description: "Number of files changed (for stagnation detection)",
+                        },
+                        error: {
+                            type: "string",
+                            description: "Error message if stuck (for stagnation detection)",
+                        },
                     },
                     required: ["branch", "storyId", "passes"],
                 },
@@ -258,6 +268,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["prdPaths"],
                 },
             },
+            {
+                name: "ralph_reset_stagnation",
+                description: "Reset stagnation counters for an execution. Use after manual intervention to allow the agent to continue.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                        resumeExecution: {
+                            type: "boolean",
+                            description: "Also set status back to 'running' if currently 'failed' (default: true)",
+                            default: true,
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_retry",
+                description: "Retry a failed PRD execution. Resets stagnation counters and generates a new agent prompt to continue from where it left off.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
         ],
     };
 });
@@ -294,6 +337,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "ralph_batch_start":
                 result = await batchStart(batchStartInputSchema.parse(args));
                 break;
+            case "ralph_reset_stagnation":
+                result = await resetStagnationTool(resetStagnationInputSchema.parse(args));
+                break;
+            case "ralph_retry":
+                result = await retry(retryInputSchema.parse(args));
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/tools/reset-stagnation.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const resetStagnationInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+    resumeExecution: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+    resumeExecution: boolean;
+}, {
+    branch: string;
+    resumeExecution?: boolean | undefined;
+}>;
+export type ResetStagnationInput = z.infer<typeof resetStagnationInputSchema>;
+export interface ResetStagnationResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    newStatus: string;
+}
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export declare function resetStagnationTool(input: ResetStagnationInput): Promise<ResetStagnationResult>;

package/dist/tools/reset-stagnation.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { findExecutionByBranch, resetStagnation, updateExecution, } from "../store/state.js";
+export const resetStagnationInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+    resumeExecution: z
+        .boolean()
+        .default(true)
+        .describe("Also set status back to 'running' if currently 'failed'"),
+});
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export async function resetStagnationTool(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Optionally resume execution
+    let newStatus = previousStatus;
+    if (input.resumeExecution && previousStatus === "failed") {
+        await updateExecution(exec.id, {
+            status: "running",
+            updatedAt: new Date(),
+        });
+        newStatus = "running";
+    }
+    return {
+        success: true,
+        branch: input.branch,
+        message: previousStatus === "failed" && input.resumeExecution
+            ? "Stagnation counters reset and execution resumed"
+            : "Stagnation counters reset",
+        previousStatus,
+        newStatus,
+    };
+}

package/dist/tools/retry.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const retryInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+}, {
+    branch: string;
+}>;
+export type RetryInput = z.infer<typeof retryInputSchema>;
+export interface RetryResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    agentPrompt: string | null;
+    progress: {
+        completed: number;
+        total: number;
+        percentage: number;
+    };
+}
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export declare function retry(input: RetryInput): Promise<RetryResult>;

package/dist/tools/retry.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { findExecutionByBranch, listUserStoriesByExecutionId, resetStagnation, updateExecution, } from "../store/state.js";
+import { generateAgentPrompt } from "../utils/agent.js";
+export const retryInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+});
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export async function retry(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Only allow retry for failed or stopped executions
+    if (previousStatus !== "failed" && previousStatus !== "stopped") {
+        return {
+            success: false,
+            branch: input.branch,
+            message: `Cannot retry execution with status '${previousStatus}'. Only 'failed' or 'stopped' executions can be retried.`,
+            previousStatus,
+            agentPrompt: null,
+            progress: { completed: 0, total: 0, percentage: 0 },
+        };
+    }
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Set status back to running
+    await updateExecution(exec.id, {
+        status: "running",
+        updatedAt: new Date(),
+    });
+    // Get stories and generate new agent prompt
+    const stories = await listUserStoriesByExecutionId(exec.id);
+    const completed = stories.filter((s) => s.passes).length;
+    const total = stories.length;
+    const agentPrompt = generateAgentPrompt(exec.branch, exec.description, exec.worktreePath || exec.projectRoot, stories.map((s) => ({
+        storyId: s.storyId,
+        title: s.title,
+        description: s.description,
+        acceptanceCriteria: s.acceptanceCriteria,
+        priority: s.priority,
+        passes: s.passes,
+    })), undefined, // contextPath - would need to re-read from PRD
+    {
+        loopCount: 0, // Reset loop context for fresh start
+        consecutiveNoProgress: 0,
+        consecutiveErrors: 0,
+        lastError: null,
+    });
+    return {
+        success: true,
+        branch: input.branch,
+        message: `Execution retried. ${total - completed} stories remaining.`,
+        previousStatus,
+        agentPrompt,
+        progress: {
+            completed,
+            total,
+            percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+        },
+    };
+}

package/dist/tools/status.d.ts

@@ -34,6 +34,7 @@ export interface StatusResult {
         completed: number;
         failed: number;
         pending: number;
+        atRisk: number;
     };
 }
 export declare function status(input: StatusInput): Promise<StatusResult>;

package/dist/tools/status.js

@@ -50,6 +50,7 @@ export async function status(input) {
         completed: executionStatuses.filter((e) => e.status === "completed").length,
         failed: executionStatuses.filter((e) => e.status === "failed").length,
         pending: executionStatuses.filter((e) => e.status === "pending").length,
+        atRisk: executionStatuses.filter((e) => e.consecutiveNoProgress >= 2 || e.consecutiveErrors >= 3).length,
     };
     return {
         executions: executionStatuses,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
   "type": "module",
   "main": "dist/index.js",