With the introduction of WebRobotService (#242), the orchestration loop can communicate via JSON files in .ralph/api/. However, there's currently no way for external systems to interact with these files through ralph-api — no RPC methods to read pending questions, submit responses, or send guidance over HTTP.
Problem
For a remote control plane (or any HTTP client) to participate in Ralph's human-in-the-loop flow, ralph-api needs endpoints that bridge the HTTP world to the file-based WebRobotService. Without these, the only way to interact is by directly writing files — which doesn't work for remote systems.
Proposed RPC methods
New robot.* domain in ralph-api:
| Method |
Purpose |
robot.question |
Returns the pending question from .ralph/api/robot-question.json, or null if none |
robot.respond |
Writes the response to .ralph/api/robot-response.json so the running loop picks it up. Publishes robot.response.received to the event stream |
robot.guidance |
Appends a human.guidance event to the active events JSONL file (found via .ralph/current-events). Publishes robot.guidance.sent to the stream |
robot.checkin |
Returns the latest checkin data from .ralph/api/robot-checkin.json (iteration, elapsed, hat) |
Proposed stream topics
| Topic |
When |
Payload |
robot.question.asked |
WebRobotService writes a question file |
{ question_id, payload, hat, iteration } |
robot.response.received |
robot.respond is called |
{ question_id, response } |
robot.guidance.sent |
robot.guidance is called |
{ text } |
robot.checkin.updated |
WebRobotService writes a checkin file |
{ iteration, elapsed_secs, hat } |
The WebRobotService can publish robot.question.asked and robot.checkin.updated via the existing _internal.publish RPC method (already available for orchestration loop → API communication).
Key files
crates/ralph-api/src/runtime/dispatch.rs — method routing (add robot.* family)
crates/ralph-api/src/stream_domain/mod.rs — stream topic definitions
crates/ralph-api/src/robot_domain.rs — new domain module
Depends on
With the introduction of
WebRobotService(#242), the orchestration loop can communicate via JSON files in.ralph/api/. However, there's currently no way for external systems to interact with these files throughralph-api— no RPC methods to read pending questions, submit responses, or send guidance over HTTP.Problem
For a remote control plane (or any HTTP client) to participate in Ralph's human-in-the-loop flow,
ralph-apineeds endpoints that bridge the HTTP world to the file-basedWebRobotService. Without these, the only way to interact is by directly writing files — which doesn't work for remote systems.Proposed RPC methods
New
robot.*domain inralph-api:robot.question.ralph/api/robot-question.json, ornullif nonerobot.respond.ralph/api/robot-response.jsonso the running loop picks it up. Publishesrobot.response.receivedto the event streamrobot.guidancehuman.guidanceevent to the active events JSONL file (found via.ralph/current-events). Publishesrobot.guidance.sentto the streamrobot.checkin.ralph/api/robot-checkin.json(iteration, elapsed, hat)Proposed stream topics
robot.question.askedWebRobotServicewrites a question file{ question_id, payload, hat, iteration }robot.response.receivedrobot.respondis called{ question_id, response }robot.guidance.sentrobot.guidanceis called{ text }robot.checkin.updatedWebRobotServicewrites a checkin file{ iteration, elapsed_secs, hat }The
WebRobotServicecan publishrobot.question.askedandrobot.checkin.updatedvia the existing_internal.publishRPC method (already available for orchestration loop → API communication).Key files
crates/ralph-api/src/runtime/dispatch.rs— method routing (addrobot.*family)crates/ralph-api/src/stream_domain/mod.rs— stream topic definitionscrates/ralph-api/src/robot_domain.rs— new domain moduleDepends on
WebRobotService: file-basedRobotServicefor API-driven human interaction #242 (WebRobotService)