README.md 11 KB
description: "The model-facing ralph tool: a fixed foreground fresh-agent loop toward one immutable objective, for users and maintainers choosing or configuring fresh-agent iteration."
kind: "package-reference"
@deepseek-ai/dsh-tool-ralph
English | 中文
Summary
ralph runs a foreground sequence of fresh child agents against one immutable objective, with each round receiving only the previous bounded report and shared workspace state. It returns when a worker reports completion or a concrete blocker, or when the configured round limit is reached; those reports are not independently verified. Parent conversation and prior child sessions are never copied into a new round. Use it only when the direct human explicitly requests Ralph-style fresh-agent iteration; use goal tools for ordinary long-running work and subagents or workflows for bounded delegation.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The ralph tool runs a fixed foreground loop: one fresh child per round works on the immutable objective in the shared workspace, and only a bounded structured report crosses rounds. Use it only when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. For ordinary long-running same-session work, use goal tools; for bounded delegation and fan-out, use plain subagents or the workflow tool.
Calling the tool
The model submits { objective, maxRounds? } and the call blocks until the whole run settles. The deployment config's maxRounds is both the default and a ceiling on a call override. The terminal result is complete, blocked, or budget-limited, carrying the last bounded report and the number of rounds started; an ordinary child failure returns an error naming the failed round and retaining the last successful handoff when one exists.
What each round sees
Each child receives only the immutable objective, its current round and cap, a shared-workspace-as-authority instruction, and the previous structured handoff; parent conversation and prior child sessions are never seeded. The workspace is the long-term memory across rounds. Reports carry a status (continue, complete, or blocked), a non-empty summary, evidence, next steps, and blocker text; invalid or oversized reports fail the workflow instead of being truncated or mistaken for cap exhaustion.
Config
| Field | Default | Meaning |
|---|---|---|
subagentProvider |
spawn |
Fresh structured-output provider used for every round. |
maxRounds |
256 |
Default and deployment ceiling for one Ralph run. |
maxHandoffChars |
16384 |
Maximum serialized characters in one round report. |
maxResultChars |
16384 |
Maximum characters in the complete successful parent result. |
The generated configuration catalog is the exhaustive source for every accepted field. The configured provider must exist, support structured output, and report inheritsParentContext: false; a call against a provider that violates this fails loudly before any round starts.
Understand the implementation
Implementation internals — click to expand
This section explains the fixed-script design and the validation and lifecycle mechanics; observable behavior is fully covered in [Use this package](#use-this-package). ### Design concept The loop is a deployment-owned fixed script: the model supplies data only and cannot alter the loop, provider route, schema, or handoff validation. The tool is an ordinary plugin over `ctx.workflowEngine` and `ctx.subagents` — no Ralph mode or fresh-agent loop is added to `agent-loop`, and the same-session goal domain stays independent. The [harness-level goal-based execution Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md) owns the policy and deferred work. ### Fixed script and routing The configured provider is carried as `WorkflowStartRequest.subagentProvider`, so the fixed script cannot inspect or change routing and the ordinary model-written `workflow` tool gains no provider selector. The resolved round cap is carried as `WorkflowStartRequest.maxTotalAgents`, coordinating the fixed loop with the engine's total-child backstop; the engine rejects a cap above its deployment ceiling before publishing a run. ### Report validation Status-specific semantics and the serialized `maxHandoffChars` ceiling are validated inside the fixed workflow and again at the consumer boundary: a continuing report needs next steps and an empty blocker, a completion report needs evidence and no next steps, and a blocked report needs a concrete blocker. Invalid, missing, or oversized reports fail the workflow. ### Lifecycle and cancellation The caller's agent is the parent of every fresh child, preserving cwd and lineage without copying its conversation. `exec.signal` enters the workflow engine and is also bridged to `run.cancel()` for implementation independence. The tool awaits `run.result` and calls `run.dispose()` in `finally`, so a cancelled parent step waits for the engine's bounded termination and child quiescence before returning. ### Render intent The pending call is a `generic` card titled `ralph` with the immutable objective as its `rawInput`; the result keeps the generic card. Both presentation functions depend only on tool arguments and the settled tool envelope, and the completion and blocker labels state that a worker reported the outcome, not independent certification. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: fixed script, provider routing, report validation, tool registration | | — | No runtime invariant companion is published; this model-facing orchestration adapter owns no independent event stream; workflow and subagent owners validate the runs and child lifecycles it starts. |Further Exploration
Read these pages when the tool-level contract is not enough. They move from the shared workflow model to the engine, the subagent seam, and the adjacent goal domain.
- Workflow subsystem — the seam contract behind the fixed loop.
- Workflow seam — the run and result vocabulary.
- Worker-thread engine — the engine that executes the fixed script.
- subagent seam — the fresh-child provider contract.
- Goal group — same-session goal tools for ordinary long-running objectives.
- Harness-level goal-based execution Agent Note — the policy, provider requirements, and deferred work.
Model Experience
System prompt
What the model sees
Every parent request in this plugin's registration scope receives the fixed routing guidance below.
Ralph guidance
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
Token effect
Small fixed guidance cost per request while the plugin is active.
KV Cache effect
Prefix-stable while the plugin scope and guidance text are unchanged. Activation or disposal may invalidate reuse from this prompt section.
Tool schema
What the model sees
The generated ralph schema exposes one required objective string and one optional maxRounds number. Provider choice, handoff size, report schema, workflow script, and orchestration behavior are deployment-owned and absent from the call schema.
Token effect
Small fixed schema cost on each request where the tool is visible.
KV Cache effect
Prefix-stable while the definition and visibility are unchanged.
Child requests and parent result
What the model sees
Each child sees the standalone fixed round prompt plus the structured-output capture contract. The parent sees only the original call and one terminal result containing a worker-reported status, round count, and pretty-printed final report; intermediate child messages and reports do not enter the parent conversation. A failed ordinary child instead yields an error with its round number and, after round one, the last successful handoff.
Token effect
Every round pays for a fresh child context. maxHandoffChars bounds cross-round state and maxResultChars independently bounds the complete successful parent text; child work remains outside the parent context.
KV Cache effect
Each fresh child has an independent request cache. The parent result appends after the reusable request prefix.
Known Limitations and Deferred Work
These limits define what the tool does not yet support. They are current constraints, not a task backlog.
- Completion is worker self-declaration — there is no independent evaluator or verifier deciding whether the objective is complete; evaluator policy and evaluator-driven continuation are deferred.
- Foreground only — there is no job id, background collection, process-resume checkpoint, scheduler, or wall-clock start policy.
- The workspace is the only cross-round long-term memory — one bounded report is the explicit handoff, and uncommitted conversational reasoning disappears with each child.
- One round is one fresh child — there is no within-round fan-out, model or provider switching, fork context, or model-call-selected provider.
- Ordinary child failure is terminal for the run — the fixed script reports the failed round and last successful handoff but does not retry; fatal workflow infrastructure failures can end before that state is returned.
- Only round count bounds aggregate effort — token, price, and elapsed-time budgets are deferred.