Crate ralph_core 

ralph-core

Core orchestration functionality for the Ralph Orchestrator framework.

This crate provides:

• The main orchestration loop for coordinating multiple agents
• Configuration loading and management
• State management for agent sessions
• Message routing between agents
• Terminal capture for session recording
• Benchmark task definitions and workspace isolation

Re-exports

pub use chaos_mode::CHAOS_COMPLETION_PROMISE;

pub use chaos_mode::ChaosModeState;

pub use diagnostics::DiagnosticsCollector;

pub use file_lock::FileLock;

pub use file_lock::LockGuard as FileLockGuard;

pub use file_lock::LockedFile;

pub use loop_completion::CompletionAction;

pub use loop_completion::CompletionError;

pub use loop_completion::LoopCompletionHandler;

pub use loop_context::LoopContext;

pub use loop_history::HistoryError;

pub use loop_history::HistoryEvent;

pub use loop_history::HistoryEventType;

pub use loop_history::HistorySummary;

pub use loop_history::LoopHistory;

pub use loop_lock::LockError;

pub use loop_lock::LockGuard;

pub use loop_lock::LockMetadata;

pub use loop_lock::LoopLock;

pub use loop_registry::LoopEntry;

pub use loop_registry::LoopRegistry;

pub use loop_registry::RegistryError;

pub use merge_queue::MergeButtonState;

pub use merge_queue::MergeEntry;

pub use merge_queue::MergeEvent;

pub use merge_queue::MergeEventType;

pub use merge_queue::MergeOption;

pub use merge_queue::MergeQueue;

pub use merge_queue::MergeQueueError;

pub use merge_queue::MergeState;

pub use merge_queue::SteeringDecision;

pub use merge_queue::merge_button_state;

pub use merge_queue::merge_execution_summary;

pub use merge_queue::merge_needs_steering;

pub use merge_queue::smart_merge_summary;

pub use planning_session::ConversationEntry;

pub use planning_session::ConversationType;

pub use planning_session::PlanningSession;

pub use planning_session::PlanningSessionError;

pub use planning_session::SessionMetadata;

pub use planning_session::SessionStatus;

pub use task::Task;

pub use task::TaskStatus;

pub use task_definition::TaskDefinition;

pub use task_definition::TaskDefinitionError;

pub use task_definition::TaskSetup;

pub use task_definition::TaskSuite;

pub use task_definition::Verification;

pub use task_store::TaskStore;

pub use workspace::CleanupPolicy;

pub use workspace::TaskWorkspace;

pub use workspace::VerificationResult;

pub use workspace::WorkspaceError;

pub use workspace::WorkspaceInfo;

pub use workspace::WorkspaceManager;

pub use worktree::SyncStats;

pub use worktree::Worktree;

pub use worktree::WorktreeConfig;

pub use worktree::WorktreeError;

pub use worktree::create_worktree;

pub use worktree::ensure_gitignore;

pub use worktree::list_ralph_worktrees;

pub use worktree::list_worktrees;

pub use worktree::remove_worktree;

pub use worktree::sync_working_directory_to_worktree;

pub use worktree::worktree_exists;

Modules

chaos_mode

Chaos Mode Runner

diagnostics

Diagnostic logging system for Ralph orchestration.

file_lock

File locking for shared resources in multi-loop scenarios.

loop_completion

Loop completion handler for worktree-based loops.

loop_context

Loop context for path resolution in multi-loop scenarios.

loop_history

Event-sourced loop history for crash recovery and debugging.

loop_lock

Loop lock mechanism for preventing concurrent Ralph loops in the same workspace.

loop_registry

Loop registry for tracking active Ralph loops across workspaces.

memory_parser

Markdown parser for the memories file format.

merge_queue

Merge queue for tracking parallel loop merges.

planning_session

Planning session management for human-in-the-loop workflows.

task

Task tracking for Ralph.

task_definition

Task definition types for benchmark harness.

task_store

Persistent task storage with JSONL format.

testing

Testing utilities for deterministic E2E tests.

utils

Utility functions for common operations.

workspace

Workspace isolation for benchmark tasks.

worktree

Git worktree management for parallel Ralph loops.

Structs

AutoCommitResult

Result of an auto-commit operation.

ChaosModeConfig

Chaos mode configuration.

CliCapture

A writer that captures all output while forwarding to an inner writer.

CliCapturePair

A pair of capture wrappers for stdout and stderr.

CliConfig

CLI backend configuration.

CoreConfig

Core paths and settings shared across all hats.

Event

A simplified event for reading from JSONL.

EventHistory

Reader for event history files.

EventLogger

Logger that writes events to a JSONL file.

EventLoop

The main event loop orchestrator.

EventLoopConfig

Event loop configuration.

EventMetadata

Metadata for an event topic.

EventParser

Parser for extracting events from CLI output.

EventReader

Reads new events from .ralph/events.jsonl since last read.

EventRecord

A logged event record for debugging.

FeaturesConfig

Feature flags for optional Ralph capabilities.

HandoffResult

Result of generating a handoff file.

HandoffWriter

Generates handoff files for session continuity.

HatConfig

Configuration for a single hat.

HatInfo

Information about a hat for prompt generation.

HatRegistry

Registry for managing and creating hats from configuration.

HatTopology

Hat topology for multi-hat mode prompt generation.

HatlessRalph

Hatless Ralph - the constant coordinator.

InstructionBuilder

Builds instructions for custom hats.

LandingConfig

Configuration for the landing handler.

LandingHandler

Handler for the landing sequence.

LandingResult

Result of the landing sequence.

LoopNameGenerator

Generator for human-readable loop names.

LoopNamingConfig

Configuration for loop naming.

LoopState

Current state of the event loop.

MalformedLine

Information about a malformed JSONL line.

MarkdownMemoryStore

A store for managing memories in markdown format.

MemoriesConfig

Memories configuration.

MemoriesFilter

Filter configuration for memory injection.

Memory

A single memory entry.

ParseResult

Result of parsing events from a JSONL file.

PlayerConfig

Configuration for session playback.

RalphConfig

Top-level configuration for Ralph Orchestrator.

Record

A timestamped record in the JSONL session file.

SessionPlayer

Plays back recorded sessions.

SessionRecorder

Records session events to a JSONL output.

SummaryWriter

Writes the loop summary file on termination.

TimestampedRecord

A parsed record with timing information for replay.

UserPrompt

A user prompt that requires human input.

Enums

ChaosOutput

Output type that chaos mode can create.

GitOpsError

Errors that can occur during git operations.

HandoffError

Errors that can occur during handoff generation.

HatBackend

Backend configuration for a hat.

InjectMode

Memory injection mode.

LandingError

Errors that can occur during landing.

MemoryType

Classification of a memory.

ReplayMode

Replay mode for session playback.

ResearchFocus

Research focus area for chaos mode.

TerminationReason

Reason the event loop terminated.

UserPromptError

Error that can occur while waiting for user response.

Constants

DEFAULT_MEMORIES_PATH

Default path for the memories file relative to the workspace root.

Functions

auto_commit_changes

Auto-commit any uncommitted changes in the repository.

clean_stashes

Clear all git stashes in the repository.

format_memories_as_markdown

Formats memories as markdown for context injection.

get_commit_summary

Get a short summary of the HEAD commit.

get_current_branch

Get the current branch name.

get_head_sha

Get the HEAD commit SHA.

get_recent_files

Get a list of files that were modified in the most recent commits.

has_uncommitted_changes

Check if the working directory has uncommitted changes.

is_working_tree_clean

Check if the working tree is clean (no uncommitted changes).

prune_remote_refs

Prune stale remote-tracking references.

truncate_to_budget

Truncates memory content to approximately fit within a token budget.

truncate_with_ellipsis

Truncates a string to a maximum number of characters, adding “…” if truncated.