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 diagnostics::DiagnosticsCollector;

pub use file_lock::FileLock;

pub use file_lock::LockGuard as FileLockGuard;

pub use file_lock::LockedFile;

pub use hooks::HookDefaults;

pub use hooks::HookEngine;

pub use hooks::HookExecutor;

pub use hooks::HookExecutorContract;

pub use hooks::HookExecutorError;

pub use hooks::HookInvocationPayload;

pub use hooks::HookMutationConfig;

pub use hooks::HookOnError;

pub use hooks::HookPayloadBuilderInput;

pub use hooks::HookPayloadContext;

pub use hooks::HookPayloadContextInput;

pub use hooks::HookPayloadIteration;

pub use hooks::HookPayloadLoop;

pub use hooks::HookPayloadMetadata;

pub use hooks::HookPhaseEvent;

pub use hooks::HookRunRequest;

pub use hooks::HookRunResult;

pub use hooks::HookSpec;

pub use hooks::HookStreamOutput;

pub use hooks::HookSuspendMode;

pub use hooks::HooksConfig;

pub use hooks::ResolvedHookSpec;

pub use hooks::SUSPEND_STATE_SCHEMA_VERSION;

pub use hooks::SuspendLifecycleState;

pub use hooks::SuspendStateRecord;

pub use hooks::SuspendStateStore;

pub use hooks::SuspendStateStoreError;

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 preflight::AcceptanceCriterion;

pub use preflight::CheckResult;

pub use preflight::CheckStatus;

pub use preflight::PreflightCheck;

pub use preflight::PreflightReport;

pub use preflight::PreflightRunner;

pub use preflight::extract_acceptance_criteria;

pub use preflight::extract_all_criteria;

pub use preflight::extract_criteria_from_file;

pub use skill::SkillEntry;

pub use skill::SkillFrontmatter;

pub use skill::SkillSource;

pub use skill::parse_frontmatter;

pub use skill_registry::SkillRegistry;

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 wave_detection::DetectedWave;

pub use wave_detection::detect_wave_events;

pub use wave_prompt::WaveWorkerContext;

pub use wave_prompt::build_wave_worker_prompt;

pub use wave_tracker::CompletedWave;

pub use wave_tracker::WaveFailure;

pub use wave_tracker::WaveProgress;

pub use wave_tracker::WaveResult;

pub use wave_tracker::WaveTracker;

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

diagnostics

Diagnostic logging system for Ralph orchestration.

file_lock

File locking for shared resources in multi-loop scenarios.

hooks

Lifecycle hook runtime contracts and orchestration primitives.

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.

preflight

Preflight checks for validating environment and configuration before running.

skill

Skill data types and frontmatter parser.

skill_registry

Skill registry for discovering, storing, and providing access to skills.

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.

wave_detection

Wave event detection from JSONL events.

wave_prompt

Wave worker prompt builder.

wave_tracker

Wave tracking state machine for concurrent hat execution.

workspace

Workspace isolation for benchmark tasks.

worktree

Git worktree management for parallel Ralph loops.

Structs

AutoCommitResult

Result of an auto-commit operation.

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.

ProcessedEvents

Result of processing events from JSONL.

ProcessedEventsWithWaves

Result of processing events from JSONL with wave events partitioned out.

RalphConfig

Top-level configuration for Ralph Orchestrator.

SkillOverride

Per-skill configuration override.

SkillsConfig

Skills configuration.

SummaryWriter

Writes the loop summary file on termination.

UrgentSteerRecord

UrgentSteerStore

UserPrompt

A user prompt that requires human input.

Enums

ConfigError

Configuration errors.

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.

TerminationReason

Reason the event loop terminated.

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.

floor_char_boundary

Finds the largest byte index <= index that is a valid UTF-8 character boundary.

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, including “…” if truncated.