Module contracts

Source

Expand description

Contracts module for Ralph configuration and queue/task JSON structures.

Responsibilities:

Own the canonical data models for config, queue, and task contracts.
Re-export the public contract types for crate-wide access.

Not handled here:

Queue persistence and IO (see crate::queue).
CLI argument parsing or command behavior (see crate::cli).

Invariants/assumptions:

Public contract types remain stable and are re-exported from this module.
Serde/schemars attributes define the wire contract and must not drift.

Re-exports§

pub use crate::constants::versions::SESSION_STATE_VERSION;

Structs§

AgentConfig: Agent runner defaults. Built-in runner IDs: codex, opencode, gemini, claude, cursor, kimi, pi. Plugin runner IDs are also supported as non-empty strings.
ArgSpec: A single CLI argument/flag.
BlockingState
CiGateConfig: Structured CI gate execution settings.
CliSpec: Root CLI spec document.
CommandSpec: A command/subcommand and its arguments.
Config: Root configuration struct for Ralph.
LoopConfig: Run loop waiting configuration for daemon/continuous mode.
MachineCliSpecDocument
MachineConfigResolveDocument
MachineConfigSafetySummary
MachineContinuationAction
MachineContinuationSummary
MachineDashboardReadDocument
MachineDecomposeDocument
MachineDoctorReportDocument
MachineErrorDocument
MachineGraphReadDocument
MachineParallelLifecycleCounts: Worker counts by lifecycle for machine run parallel-status (document v3+).
MachineParallelStatusDocument
MachineQueuePaths
MachineQueueReadDocument
MachineQueueRepairDocument
MachineQueueUndoDocument
MachineQueueUnlockInspectDocument
MachineQueueValidateDocument
MachineResumeDecision
MachineRunEventEnvelope
MachineRunSummaryDocument
MachineSystemInfoDocument
MachineTaskCreateDocument
MachineTaskCreateRequest
MachineTaskMutationDocument
MachineValidationWarning
MachineWorkspaceOverviewDocument
NotificationConfig: Desktop notification configuration.
ParallelConfig: Parallel run-loop configuration.
PhaseOverrideConfig: Per-phase configuration overrides for runner, model, and reasoning effort.
PhaseOverrides: Phase overrides container for Phase 1/2/3 execution.
PhaseSettingsSnapshot: Per-phase settings persisted for display/logging purposes.
PluginConfig: Per-plugin configuration.
PluginsConfig: Plugin configuration container.
QueueAgingThresholds: Aging threshold configuration for ralph queue aging.
QueueConfig: Queue-related configuration.
QueueFile
RunnerCliConfigRoot
RunnerCliOptionsPatch
RunnerRetryConfig: Runner retry/backoff configuration for transient failure handling.
SessionState: Session state persisted to enable crash recovery.
Task
TaskAgent
WebhookConfig: Webhook configuration for HTTP task event notifications.

Enums§

BlockingReason
BlockingStatus
ClaudePermissionMode
GitPublishMode: Git publish mode for post-run repository changes.
GitRevertMode: Git revert mode for handling runner/supervision errors.
MachineErrorCode
MachineQueueUnlockCondition
MachineRunEventKind
Model
ModelEffort
ProjectType: Project type classification.
ReasoningEffort
Runner
RunnerApprovalMode
RunnerOutputFormat
RunnerPlanMode
RunnerSandboxMode
RunnerVerbosity
ScanPromptVersion: Scan prompt version to use for scan operations.
TaskPriority: Task priority used for queue ordering and display.
TaskStatus
UnsupportedOptionPolicy
WebhookEventSubscription: Webhook event subscription type for config. Each variant corresponds to a WebhookEventType, plus Wildcard for “all events”.
WebhookQueuePolicy: Backpressure policy for webhook delivery queue.

Module contracts

Module contracts Copy item path

Re-exports§

Structs§

Enums§

Constants§

Module contracts