Skip to content

Add robot.* RPC methods and stream topics to ralph-api #243

@moltar

Description

@moltar

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions