Ralph Loop Middleware

Ralph Loop runs a verifier-first goal loop inside the normal agent middleware pipeline. It keeps the agent working across bounded continuation turns until the model signals that it is ready to finish and trusted verifier evidence agrees.

The middleware provider name is ralph-loop.

Core Idea

Ralph Loop is no longer just “retry until <promise>DONE</promise>”. The completion marker is treated as a finalization intent, not proof that the task is complete.

By default, completion is accepted only when both conditions are true:

• The latest AI answer includes <promise>DONE</promise>.
• The latest trusted verifier evidence has passed.

If the model claims completion without passing verifier evidence, Ralph Loop rejects the completion, creates a compact continuation prompt, clears the message history for that channel, and routes the run back to the model.

Goal Slash Command

When an agent is connected to Ralph Loop, the middleware exposes a runtime slash command:

/goal <objective>

The command is declared by RalphLoopMiddleware.meta.slashCommands. The runtime command is sent to the composer as an insert_invocation command, so the UI inserts /goal ... rather than expanding the full prompt template on the client.

The default /goal template asks the agent to follow:

Plan -> Act -> Verify -> Reflect -> Retry

It also tells the agent to use the strongest applicable verifier before finalizing. If UI screens or visual parity are part of the goal, the template explicitly asks the agent to use Playwright Interactive to inspect and compare the result.

Completion Marker

Ralph Loop still uses this marker:

<promise>DONE</promise>

The marker means “the model believes the goal is ready to finalize”. It does not bypass verification. When completion is accepted, the middleware removes the marker from the visible answer.

Verifier Evidence

Ralph Loop collects recent ToolMessages from configured verifier tools. The default trusted verifier tool list is:

["sandbox_shell"]

The middleware matches verifier output back to the originating AI tool call and records:

• tool name
• tool call id
• command, when available
• status, either pass or fail
• output content
• observed timestamp

Verifier evidence is recorded as failed when the tool output indicates a nonzero exit, timeout, or tool error. Otherwise, it is recorded as passing evidence.

Ralph Loop does not execute verifier tools directly from the middleware hook. The model must call tools through the normal tool pipeline, so streaming, HITL, tool limits, and tool retry middleware still apply.

How It Works

Hook	Behavior
beforeAgent	Starts or resumes Ralph Loop state. Active state is preserved across turns unless the user starts a new objective or the previous run reached a terminal status.
wrapModelCall	Appends the verifier-first completion rule to the system message. During retries, it sends a compact continuation prompt instead of the full previous message history.
afterModel	Extracts verifier evidence, checks the completion marker, gates completion on verifier status, and either accepts completion, continues the loop, or stops at the iteration budget.

The continuation prompt carries:

• original objective
• current iteration
• compact runtime summary
• last verifier evidence
• continuation reason
• expected next behavior

It tells the agent to continue with Plan -> Act -> Verify -> Reflect -> Retry, fix failed verification, run a verifier when evidence is missing, and only then finalize with the completion marker.

If the original human message contained structured content parts, Ralph Loop preserves them behind the continuation prompt.

Configuration

Field	Type	Default	Description
maxIterations	number	20	Maximum number of automatic verifier-first continuation turns.
requireVerifier	boolean	true	Require trusted passing verifier evidence before accepting the completion marker.
verifierToolNames	string[]	["sandbox_shell"]	Tool names whose ToolMessages count as trusted verifier evidence.
verifierInstructions	string	""	Additional instructions for how the agent should verify the goal.
maxRuntimeSummaryChars	number	4000	Maximum compact runtime summary length carried into continuation prompts.

Example:

{
  "maxIterations": 8,
  "requireVerifier": true,
  "verifierToolNames": ["sandbox_shell"],
  "verifierInstructions": "Run the relevant test command before finalizing. For UI parity work, inspect the changed screens with Playwright Interactive.",
  "maxRuntimeSummaryChars": 3000
}

Runtime State

Ralph Loop stores these state fields:

Field	Description
ralphLoopIteration	Current continuation iteration.
ralphLoopOriginalHumanContent	Original human message content or structured message parts.
ralphLoopOriginalTaskText	Original plain-text task extracted from runtime human input when available.
ralphLoopStatus	Current run status: active, completed, blocked, or budget_exhausted.
ralphLoopRunId	Identifier for the active Ralph Loop run.
ralphLoopRuntimeSummary	Compact summary carried across cleaned retry turns.
ralphLoopLastVerifier	Latest trusted verifier evidence.
ralphLoopStopReason	Reason the loop stopped or continued.

Terminal statuses are completed, blocked, and budget_exhausted. A new objective or a terminal prior run starts a fresh run.

Budget Exhaustion

When maxIterations is reached before the verifier-first completion contract is satisfied, Ralph Loop stops retrying and appends a verifier-aware notice to the latest answer:

Ralph Loop stopped after reaching <maxIterations> automatic retries before the verifier-first completion contract was satisfied.

Last verifier evidence:
...

The run status becomes budget_exhausted.

When To Use

Use Ralph Loop for goals where the agent should keep working until there is external evidence of completion:

• migrations and refactors that must pass tests
• UI parity tasks that need Playwright Interactive inspection
• long implementation tasks where the model may stop early
• research or analysis tasks with explicit verifier commands
• tasks where a clean continuation prompt is better than carrying a cluttered history

Avoid using Ralph Loop as a full task runtime. It does not add a /goal product surface with pause, resume, clear, reports, or separate goal runtime state. It stays inside the existing middleware hook shape.

Troubleshooting

• The final answer shows no <promise>DONE</promise>: This is expected. Ralph Loop strips the marker after accepting completion.
• The model says it is done but keeps looping: The completion marker was not accompanied by passing trusted verifier evidence.
• Verifier output failed: Ralph Loop will continue with the failure context so the agent can fix the root cause and verify again.
• No verifier is detected: Ensure the agent has access to a tool listed in verifierToolNames, or configure the list for your verifier tool.
• The agent stops with a budget notice: Increase maxIterations, clarify the objective, or inspect the last verifier evidence to see what blocked completion.