Documentation Index
Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
Use this file to discover all available pages before exploring further.
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:
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
Completion Marker
Ralph Loop still uses this marker:
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:
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. |
- 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. |
{
"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. |
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:
...
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.
