Struct EventLoop 

pub struct EventLoop { /* private fields */ }

The main event loop orchestrator.

Implementations

impl EventLoop

pub fn new(config: RalphConfig) -> Self

Creates a new event loop from configuration.

pub fn with_context(config: RalphConfig, context: LoopContext) -> Self

Creates a new event loop with a loop context for path resolution.

The loop context determines where events, tasks, and other state files are located. Use this for multi-loop scenarios where each loop runs in an isolated workspace (git worktree).

pub fn with_context_and_diagnostics( config: RalphConfig, context: LoopContext, diagnostics: DiagnosticsCollector, ) -> Self

Creates a new event loop with explicit loop context and diagnostics.

pub fn with_diagnostics( config: RalphConfig, diagnostics: DiagnosticsCollector, ) -> Self

Creates a new event loop with explicit diagnostics collector (for testing).

pub fn loop_context(&self) -> Option<&LoopContext>

Returns the loop context, if one was provided.

pub fn state(&self) -> &LoopState

Returns the current loop state.

pub fn config(&self) -> &RalphConfig

Returns the configuration.

pub fn registry(&self) -> &HatRegistry

Returns the hat registry.

pub fn get_hat_backend(&self, hat_id: &HatId) -> Option<&HatBackend>

Gets the backend configuration for a hat.

If the hat has a backend configured, returns that. Otherwise, returns None (caller should use global backend).

pub fn add_observer<F>(&mut self, observer: F)

where F: Fn(&Event) + Send + 'static,

Adds an observer that receives all published events.

Multiple observers can be added (e.g., session recorder + TUI). Each observer is called before events are routed to subscribers.

pub fn set_observer<F>(&mut self, observer: F)

where F: Fn(&Event) + Send + 'static,

👎Deprecated since 2.0.0: Use add_observer instead

Sets a single observer, clearing any existing observers.

Prefer add_observer when multiple observers are needed.

pub fn check_termination(&self) -> Option<TerminationReason>

Checks if any termination condition is met.

pub fn initialize(&mut self, prompt_content: &str)

Initializes the loop by publishing the start event.

pub fn initialize_resume(&mut self, prompt_content: &str)

Initializes the loop for resume mode by publishing task.resume.

Per spec: “User can run ralph resume to restart reading existing scratchpad.” The planner should read the existing scratchpad rather than doing fresh gap analysis.

pub fn next_hat(&self) -> Option<&HatId>

Gets the next hat to execute (if any have pending events).

Per “Hatless Ralph” architecture: When custom hats are defined, Ralph is always the executor. Custom hats define topology (pub/sub contracts) that Ralph uses for coordination context, but Ralph handles all iterations.

• Solo mode (no custom hats): Returns “ralph” if Ralph has pending events
• Multi-hat mode (custom hats defined): Always returns “ralph” if ANY hat has pending events

pub fn has_pending_events(&self) -> bool

Checks if any hats have pending events.

Use this after process_output to detect if the LLM failed to publish an event. If false after processing, the loop will terminate on the next iteration.

pub fn has_pending_human_events(&self) -> bool

Checks if any pending events are human-related (human.response, human.guidance).

Used to skip cooldown delays when a human event is next, since we don’t want to artificially delay the response to a human interaction.

pub fn get_hat_publishes(&self, hat_id: &HatId) -> Vec<String>

Gets the topics a hat is allowed to publish.

Used to build retry prompts when the LLM forgets to publish an event.

pub fn inject_fallback_event(&mut self) -> bool

Injects a fallback event to recover from a stalled loop.

When no hats have pending events (agent failed to publish), this method injects a task.resume event which Ralph will handle to attempt recovery.

Returns true if a fallback event was injected, false if recovery is not possible.

pub fn build_prompt(&mut self, hat_id: &HatId) -> Option<String>

Builds the prompt for a hat’s execution.

Per “Hatless Ralph” architecture:

• Solo mode: Ralph handles everything with his own prompt
• Multi-hat mode: Ralph is the sole executor, custom hats define topology only

When in multi-hat mode, this method collects ALL pending events across all hats and builds Ralph’s prompt with that context. The ## HATS section in Ralph’s prompt documents the topology for coordination awareness.

If memories are configured with inject: auto, this method also prepends primed memories to the prompt context. If a scratchpad file exists and is non-empty, its content is also prepended (before memories).

pub fn build_ralph_prompt(&self, prompt_content: &str) -> String

Builds the Ralph prompt (coordination mode).

pub fn get_active_hat_id(&self) -> HatId

Returns the primary active hat ID for display purposes. Returns the first active hat, or “ralph” if no specific hat is active.

pub fn record_event_count(&mut self) -> usize

Records the current event count before hat execution.

Call this before executing a hat, then use check_default_publishes after execution to inject a fallback event if needed.

pub fn check_default_publishes(&mut self, hat_id: &HatId, _events_before: usize)

Checks if hat wrote any events, and injects default if configured.

Call this after hat execution with the count from record_event_count. If no new events were written AND the hat has default_publishes configured, this will inject the default event automatically.

pub fn bus(&mut self) -> &mut EventBus

Returns a mutable reference to the event bus for direct event publishing.

This is primarily used for planning sessions to inject user responses as events into the orchestration loop.

pub fn process_output( &mut self, hat_id: &HatId, output: &str, success: bool, ) -> Option<TerminationReason>

Processes output from a hat execution.

Returns the termination reason if the loop should stop.

pub fn add_cost(&mut self, cost: f64)

Adds cost to the cumulative total.

pub fn process_events_from_jsonl(&mut self) -> Result<bool>

Processes events from JSONL and routes orphaned events to Ralph.

Also handles backpressure for malformed JSONL lines by:

1. Emitting event.malformed system events for each parse failure
2. Tracking consecutive failures for termination check
3. Resetting counter when valid events are parsed

Returns true if Ralph should be invoked to handle orphaned events.

pub fn check_ralph_completion(&self, output: &str) -> bool

Checks if output contains LOOP_COMPLETE from Ralph.

Only Ralph can trigger loop completion. Hat outputs are ignored.

pub fn publish_terminate_event(&mut self, reason: &TerminationReason) -> Event

Publishes the loop.terminate system event to observers.

Per spec: “Published by the orchestrator (not agents) when the loop exits.” This is an observer-only event—hats cannot trigger on it.

Returns the event for logging purposes.

pub fn telegram_shutdown_flag(&self) -> Option<Arc<AtomicBool>>

Returns the Telegram service’s shutdown flag, if active.

Signal handlers can set this flag to interrupt wait_for_response() without waiting for the full timeout.

pub fn telegram_service(&self) -> Option<&TelegramService>

Returns a reference to the Telegram service, if active.

pub fn telegram_service_mut(&mut self) -> Option<&mut TelegramService>

Returns a mutable reference to the Telegram service, if active.

pub fn check_for_user_prompt(&self, events: &[Event]) -> Option<UserPrompt>

Check if any event is a user.prompt event.

Returns the first user prompt event found, or None.