Python API Reference ¶

ralph.config.bootstrap.ensure_local_configs(agent_dir, *, force=False)[source]¶

Ensure the full project-local config set exists.

Parameters:

agent_dir (Path) – The .agent directory to write configs into.
force (bool) – When True, overwrite existing files (backs them up first).

Returns:

List of BootstrapResult, one per config file.

Return type:

ralph.config.bootstrap.ensure_local_main_config(agent_dir, *, force=False)[source]¶

Ensure the project-local main override exists.

Parameters:

agent_dir (Path) – The .agent directory to write configs into.
force (bool) – When True, overwrite an existing file (backing it up first).

Returns:

BootstrapResult describing the action taken for .agent/ralph-workflow.toml.

Return type:

BootstrapResult

ralph.config.bootstrap.ensure_local_support_configs(agent_dir, *, force=False)[source]¶

Ensure the standard project-local policy and MCP files exist.

This scaffolds the .agent/ files Ralph needs for project-local runtime behavior without creating the optional project-local main override.

Parameters:

agent_dir (Path) – The .agent directory to write configs into.
force (bool) – When True, overwrite existing files (backs them up first).

Returns:

List of BootstrapResult, one per support file.

Return type:

ralph.config.bootstrap.regenerate_all(*, global_dir=None, agent_dir=None)[source]¶

Regenerate all configs from bundled defaults, backing up existing files.

Parameters:

global_dir (Path | None) – Override the global config directory. Defaults to resolve_global_config_dir().
agent_dir (Path | None) – The .agent directory to regenerate local configs in. Skipped when None.

Returns:

Flat list of BootstrapResult for every file touched.

Return type:

ExhaustedAnalysisBypassResult

ralph.config.bootstrap.resolve_global_config_dir(env=None)[source]¶

Resolve the user-global config directory.

Honors XDG_CONFIG_HOME when set; falls back to ~/.config.

Parameters:: env (Mapping[str, str] | None) – Environment mapping to read from. Uses os.environ when None.
Returns:: Path to the config directory.
Return type:: Path

ralph.config.enums¶

Backward-compatible enum re-exports for ralph configuration.

NOTE: PipelinePhase is now a type alias to str (not a StrEnum). Phase names are loaded from pipeline.toml at startup. Well-known phases are exposed as module-level constants for use in built-in phase handlers.

class ralph.config.enums.AgentTransport(*values)[source]¶

Bases: StrEnum

Invocation/MCP transport type for an agent runtime.

CLAUDE¶: Claude Code compatible invocation/MCP transport.

CLAUDE_INTERACTIVE¶: Unattended interactive Claude Code transport.

CODEX¶: Codex CLI compatible invocation/MCP transport.

OPENCODE¶: OpenCode compatible invocation/MCP transport.

GENERIC¶: No special transport support.

AGY¶: Google Anti Gravity compatible invocation/MCP transport.

class ralph.config.enums.JsonParserType(*values)[source]¶

Bases: StrEnum

JSON parser type for agent output parsing.

CLAUDE¶: Parser for Claude’s NDJSON streaming format

CODEX¶: Parser for Codex’s NDJSON streaming format

GEMINI¶: Parser for Gemini’s NDJSON streaming format

OPENCODE¶: Parser for OpenCode’s NDJSON streaming format

GENERIC¶: Generic NDJSON parser for other agents

class ralph.config.enums.PauseOnExit(*values)[source]¶

Bases: StrEnum

Pause behavior before process exit.

AUTO¶: Pause only on standalone failure

ALWAYS¶: Always pause before exit

NEVER¶: Never pause before exit

ralph.config.enums.PipelinePhase¶: alias of str

class ralph.config.enums.RecoveryStrategy(*values)[source]¶

Bases: StrEnum

Recovery strategy when pipeline encounters failures.

FAIL¶: Fail immediately on errors

AUTO¶: Attempt automatic recovery

FORCE¶: Force through errors

class ralph.config.enums.Verbosity(*values)[source]¶

Bases: StrEnum

Verbosity level for Ralph output.

QUIET¶: Minimal output (errors only)

NORMAL¶: Default verbosity level

VERBOSE¶: More detailed output

FULL¶: Full output with all details

DEBUG¶: Debug-level output for troubleshooting

ralph.config.loader¶

Layered TOML configuration loader.

Merge order (lowest to highest priority):

Embedded defaults (Pydantic field defaults)
~/.config/ralph-workflow.toml
.agent/ralph-workflow.toml (project-local)
CLI flag overrides

This module handles the three-layer configuration merging from the Rust implementation: - Global config: ~/.config/ralph-workflow.toml - Local config: .agent/ralph-workflow.toml - CLI overrides: Applied last via dict patch before Pydantic validation

ralph.config.loader.deep_merge(base, override)[source]¶

Recursively merge override into base; override wins on conflict.

Parameters:

base (dict[str, object]) – The base dictionary to merge into.
override (dict[str, object]) – The override dictionary to merge.

Returns:

A new dictionary with the merged result.

Return type:

dict[str, object]

ralph.config.loader.load_config(config_path=None, cli_overrides=None, workspace_scope=None)[source]¶

Build merged UnifiedConfig from all layers.

Merge order (lowest to highest priority):

Embedded defaults (Pydantic field defaults)
~/.config/ralph-workflow.toml
.agent/ralph-workflow.toml (project-local)
CLI flag overrides

Parameters:

config_path (Path | None) – Optional path to local config file. Defaults to .agent/ralph-workflow.toml.
cli_overrides (dict[str, object] | None) – Optional dictionary of CLI flag overrides.
workspace_scope (WorkspaceScope | None)

Returns:

Validated UnifiedConfig instance.

Raises:

SystemExit – If configuration validation fails.

Return type:

UnifiedConfig

ralph.config.loader.load_local_only(config_path)[source]¶

Load configuration from a specific path without merging global config.

Parameters:: config_path (Path) – Path to the configuration file.
Returns:: Validated UnifiedConfig instance.
Return type:: UnifiedConfig

ralph.config.loader.load_toml(path)[source]¶

Read a TOML file; return empty dict if missing.

Parameters:: path (Path) – Path to the TOML file.
Returns:: Parsed TOML content as a dictionary, or empty dict if file doesn’t exist.
Return type:: dict[str, object]

ralph.config.mcp_loader¶

Three-layer mcp.toml loader.

Merge order (lowest → highest priority):

Bundled default - ralph/policy/defaults/mcp.toml (ships in wheel)
User-global - $XDG_CONFIG_HOME/ralph-workflow-mcp.toml
(default: ~/.config/ralph-workflow-mcp.toml)
Project-local - .agent/mcp.toml (resolved via WorkspaceScope)

Unlike the main config loader, TOML parse errors here are fail-fast: any malformed file triggers a typed exit rather than a silent empty-dict fallback.

exception ralph.config.mcp_loader.McpConfigError(message, *, code=1)[source]¶

Bases: SystemExit

Typed fail-fast exit for invalid MCP configuration.

Parameters:

message (str)
code (int)

Return type:

None

ralph.config.mcp_loader.bundled_default_mcp_config_path()[source]¶

Return the path to the bundled default MCP configuration file.

Return type:: Path

ralph.config.mcp_loader.global_mcp_config_path()[source]¶

Return the user-level global MCP config path, respecting XDG_CONFIG_HOME.

Return type:: Path

ralph.config.mcp_loader.load_mcp_config(workspace_scope=None, config_path=None)[source]¶

Build merged McpConfig from all layers.

Parameters:

workspace_scope (WorkspaceScope | None) – Provides the project-local .agent/ root. Not used when config_path is given.
config_path (Path | None) – Explicit override for the project-local layer.

Returns:

Validated McpConfig.

Raises:

McpConfigError – On TOML parse error, schema validation failure, or unknown fallback backend reference.

Return type:

McpConfig

ralph.config.mcp_loader.local_mcp_config_path(workspace_scope)[source]¶

Return the workspace-local MCP config path for the given workspace scope.

Parameters:: workspace_scope (WorkspaceScope)
Return type:: Path

ralph.config.mcp_models¶

Pydantic models for mcp.toml.

class ralph.config.mcp_models.McpConfig(*, mcp_servers=<factory>, web_search=<factory>, web_visit=<factory>, media=<factory>)[source]¶

Bases: BaseModel

Top-level mcp.toml document.

Parameters:

mcp_servers (dict[str, McpServerSpec])
web_search (WebSearchConfig)
web_visit (WebVisitConfig)
media (MediaConfig)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.mcp_models.McpServerSpec(*, name, transport, url=None, command=None, args=<factory>, env=<factory>, chains=None)[source]¶

Bases: BaseModel

Schema for a single MCP server entry in mcp.toml.

Parameters:

name (str)
transport (Literal['http', 'stdio'])
url (str | None)
command (str | None)
args (list[str])
env (dict[str, str])
chains (list[str] | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.mcp_models.MediaConfig(*, enabled=True, max_inline_bytes=5242880)[source]¶

Bases: BaseModel

Multimodal media support config in mcp.toml.

Broad multimodal support (images, PDFs, audio, video, documents) is enabled by default. Disable with [media] enabled = false in mcp.toml.

Parameters:

enabled (bool)
max_inline_bytes (int)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.mcp_models.WebSearchBackendSpec(*, backend, url=None, api_key=None, api_key_env=None)[source]¶

Bases: BaseModel

Backend configuration for built-in web search providers.

Parameters:

backend (Literal['ddgs', 'searxng', 'tavily', 'brave', 'exa'])
url (str | None)
api_key (str | None)
api_key_env (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.mcp_models.WebSearchConfig(*, enabled=True, backend='ddgs', fallback=<factory>, backends=<factory>)[source]¶

Bases: BaseModel

Top-level web_search config in mcp.toml.

Parameters:

enabled (bool)
backend (str)
fallback (list[str])
backends (dict[str, WebSearchBackendSpec])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.mcp_models.WebVisitConfig(*, enabled=True, timeout_ms=15000, max_bytes=2097152, user_agent='RalphWorkflow/1.0 (+https://ralph-workflow.dev)', allow_private_networks=False, extract_links=False)[source]¶

Bases: BaseModel

Top-level web_visit config in mcp.toml.

Parameters:

enabled (bool)
timeout_ms (int)
max_bytes (int)
user_agent (str)
allow_private_networks (bool)
extract_links (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.models¶

Pydantic v2 models for Ralph configuration.

class ralph.config.models.AgentConfig(*, cmd, output_flag=None, yolo_flag=None, verbose_flag=None, can_commit=False, json_parser=JsonParserType.GENERIC, model_flag=None, print_flag=None, streaming_flag=None, session_flag=None, display_name=None, transport=None)[source]¶

Bases: BaseModel

Configuration for a single AI agent.

Parameters:

cmd (str)
output_flag (str | None)
yolo_flag (str | None)
verbose_flag (str | None)
can_commit (bool)
json_parser (JsonParserType)
model_flag (str | None)
print_flag (str | None)
streaming_flag (str | None)
session_flag (str | None)
display_name (str | None)
transport (AgentTransport | None)

cmd¶

Base command to run the agent.

Type:: str

output_flag¶

Optional output format flag for streaming JSON.

Type:: str | None

yolo_flag¶

Optional autonomous/non-interactive flag string.

Type:: str | None

verbose_flag¶

Flag for verbose output.

Type:: str | None

can_commit¶

Whether the agent can run git commit.

Type:: bool

json_parser¶

Which JSON parser to use for agent output.

Type:: JsonParserType

model_flag¶

Optional model/provider flag.

Type:: str | None

print_flag¶

Optional print flag for non-interactive output mode.

Type:: str | None

streaming_flag¶

Optional streaming flag for partial JSON messages.

Type:: str | None

session_flag¶

Optional session continuation flag template.

Type:: str | None

display_name¶

Human-readable display name for UI/UX.

Type:: str | None

transport¶

Invocation/MCP transport type for the agent runtime.

Type:: AgentTransport | None

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_context)[source]¶

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:: _context (object)
Return type:: None

class ralph.config.models.CcsConfig(*, output_flag='--output-format=stream-json', yolo_flag='--permission-mode auto', verbose_flag='--verbose', print_flag='--print', streaming_flag='--include-partial-messages', json_parser='claude', session_flag='--resume {}', can_commit=True)[source]¶

Bases: BaseModel

Headless-by-design Claude Code Switch (CCS) defaults.

CCS aliases explicitly run Claude in non-interactive streaming mode (--print --output-format=stream-json). That is the intended explicit headless Claude path for users who configure [ccs_aliases]. The built-in claude agent runs in interactive mode by default.

Parameters:

output_flag (str)
yolo_flag (str)
verbose_flag (str)
print_flag (str)
streaming_flag (str)
json_parser (str)
session_flag (str)
can_commit (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.models.GeneralConfig(*, verbosity=2, workflow=<factory>, developer_iters=5, developer_context=1, prompt_path=None, templates_dir=None, git_user_name=None, git_user_email=None, provider_fallback=<factory>, max_same_agent_retries=10, max_commit_residual_retries=10, max_retries=3, retry_delay_ms=1000, backoff_multiplier=2.0, max_backoff_ms=60000, max_cycles=3, execution_history_limit=1000, agent_idle_timeout_seconds=300.0, agent_idle_drain_window_seconds=0.5, agent_idle_max_waiting_on_child_seconds=1800.0, agent_idle_poll_interval_seconds=0.05, agent_parent_exit_grace_seconds=5.0, agent_descendant_wait_timeout_seconds=30.0, agent_descendant_wait_poll_seconds=0.5, agent_process_exit_wait_seconds=30.0, agent_max_session_seconds=None, agent_waiting_status_interval_seconds=30.0, agent_suspect_waiting_on_child_seconds=600.0, agent_idle_no_progress_waiting_on_child_seconds=600.0, agent_child_progress_ttl_seconds=45.0, agent_child_heartbeat_ttl_seconds=15.0, agent_child_stale_label_ttl_seconds=10.0, agent_child_exit_reconcile_seconds=5.0)[source]¶

Bases: BaseModel

[general] section of ralph-workflow.toml.

Parameters:

verbosity (int)
workflow (GeneralWorkflowFlags)
developer_iters (Annotated[int, Ge(ge=1)])
developer_context (Annotated[int, Ge(ge=1)])
prompt_path (Path | None)
templates_dir (Path | None)
git_user_name (str | None)
git_user_email (str | None)
provider_fallback (dict[str, list[str]])
max_same_agent_retries (Annotated[int, Ge(ge=0)])
max_commit_residual_retries (Annotated[int, Ge(ge=0)])
max_retries (Annotated[int, Ge(ge=0)])
retry_delay_ms (Annotated[int, Ge(ge=0)])
backoff_multiplier (Annotated[float, Ge(ge=1.0)])
max_backoff_ms (Annotated[int, Ge(ge=0)])
max_cycles (Annotated[int, Ge(ge=1)])
execution_history_limit (Annotated[int, Ge(ge=1)])
agent_idle_timeout_seconds (Annotated[float, Gt(gt=0)])
agent_idle_drain_window_seconds (Annotated[float, Ge(ge=0)])
agent_idle_max_waiting_on_child_seconds (Annotated[float, Gt(gt=0)])
agent_idle_poll_interval_seconds (Annotated[float, Gt(gt=0)])
agent_parent_exit_grace_seconds (Annotated[float, Ge(ge=0)])
agent_descendant_wait_timeout_seconds (Annotated[float, Ge(ge=0)])
agent_descendant_wait_poll_seconds (Annotated[float, Gt(gt=0)])
agent_process_exit_wait_seconds (Annotated[float, Ge(ge=0)])
agent_max_session_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_waiting_status_interval_seconds (Annotated[float, Gt(gt=0)])
agent_suspect_waiting_on_child_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_idle_no_progress_waiting_on_child_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_child_progress_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_heartbeat_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_stale_label_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_exit_reconcile_seconds (Annotated[float, Ge(ge=0)])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.models.UnifiedConfig(*, general=<factory>, ccs=<factory>, agents=<factory>, ccs_aliases=<factory>, agent_chains=<factory>, agent_drains=<factory>, prompt_helper=<factory>)[source]¶

Bases: BaseModel

Top-level merged configuration (global + local + CLI overrides).

Parameters:

general (GeneralConfig)
ccs (CcsConfig)
agents (dict[str, AgentConfig])
ccs_aliases (dict[str, str | CcsAliasConfig])
agent_chains (dict[str, AgentChainConfig])
agent_drains (dict[str, AgentDrainConfig])
prompt_helper (PromptHelperConfig)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.welcome¶

First-run welcome banner and agent availability helper.

ralph.config.welcome.emit_first_run_welcome(console, results, *, agent_registry=None, is_regenerate=False, display_context)[source]¶

Print a structured first-run welcome panel.

Parameters:

console (object) – A rich.console.Console-like object with a .print() method.
results (list[BootstrapResult]) – Bootstrap results from a bootstrap operation.
agent_registry (HasListAgents | None) – Optional agent registry for availability checking.
is_regenerate (bool) – Whether this is a regenerate (–regenerate-config) operation.
display_context (DisplayContext) – Display context for adaptive layout (required).

Return type:

None

ralph.config.agent_config¶

Agent configuration model definitions.

class ralph.config.agent_config.AgentConfig(*, cmd, output_flag=None, yolo_flag=None, verbose_flag=None, can_commit=False, json_parser=JsonParserType.GENERIC, model_flag=None, print_flag=None, streaming_flag=None, session_flag=None, display_name=None, transport=None)[source]¶

Bases: BaseModel

Configuration for a single AI agent.

Parameters:

cmd (str)
output_flag (str | None)
yolo_flag (str | None)
verbose_flag (str | None)
can_commit (bool)
json_parser (JsonParserType)
model_flag (str | None)
print_flag (str | None)
streaming_flag (str | None)
session_flag (str | None)
display_name (str | None)
transport (AgentTransport | None)

cmd¶

Base command to run the agent.

Type:: str

output_flag¶

Optional output format flag for streaming JSON.

Type:: str | None

yolo_flag¶

Optional autonomous/non-interactive flag string.

Type:: str | None

verbose_flag¶

Flag for verbose output.

Type:: str | None

can_commit¶

Whether the agent can run git commit.

Type:: bool

json_parser¶

Which JSON parser to use for agent output.

Type:: JsonParserType

model_flag¶

Optional model/provider flag.

Type:: str | None

print_flag¶

Optional print flag for non-interactive output mode.

Type:: str | None

streaming_flag¶

Optional streaming flag for partial JSON messages.

Type:: str | None

session_flag¶

Optional session continuation flag template.

Type:: str | None

display_name¶

Human-readable display name for UI/UX.

Type:: str | None

transport¶

Invocation/MCP transport type for the agent runtime.

Type:: AgentTransport | None

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_context)[source]¶

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:: _context (object)
Return type:: None

ralph.config.agent_transport¶

Agent transport enum for runtime invocation/MCP support.

class ralph.config.agent_transport.AgentTransport(*values)[source]¶

Bases: StrEnum

Invocation/MCP transport type for an agent runtime.

CLAUDE¶: Claude Code compatible invocation/MCP transport.

CLAUDE_INTERACTIVE¶: Unattended interactive Claude Code transport.

CODEX¶: Codex CLI compatible invocation/MCP transport.

OPENCODE¶: OpenCode compatible invocation/MCP transport.

GENERIC¶: No special transport support.

AGY¶: Google Anti Gravity compatible invocation/MCP transport.

ralph.config.ccs_config¶

CCS configuration model definitions.

class ralph.config.ccs_config.CcsAliasConfig(*, cmd, output_flag=None, yolo_flag=None, verbose_flag=None, print_flag=None, streaming_flag=None, json_parser=None, can_commit=None, model_flag=None, session_flag=None)[source]¶

Bases: BaseModel

Per-alias CCS configuration (table form).

Parameters:

cmd (str)
output_flag (str | None)
yolo_flag (str | None)
verbose_flag (str | None)
print_flag (str | None)
streaming_flag (str | None)
json_parser (str | None)
can_commit (bool | None)
model_flag (str | None)
session_flag (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.ccs_config.CcsConfig(*, output_flag='--output-format=stream-json', yolo_flag='--permission-mode auto', verbose_flag='--verbose', print_flag='--print', streaming_flag='--include-partial-messages', json_parser='claude', session_flag='--resume {}', can_commit=True)[source]¶

Bases: BaseModel

Headless-by-design Claude Code Switch (CCS) defaults.

Parameters:

output_flag (str)
yolo_flag (str)
verbose_flag (str)
print_flag (str)
streaming_flag (str)
json_parser (str)
session_flag (str)
can_commit (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.general_config¶

General Ralph configuration model definitions.

class ralph.config.general_config.GeneralConfig(*, verbosity=2, workflow=<factory>, developer_iters=5, developer_context=1, prompt_path=None, templates_dir=None, git_user_name=None, git_user_email=None, provider_fallback=<factory>, max_same_agent_retries=10, max_commit_residual_retries=10, max_retries=3, retry_delay_ms=1000, backoff_multiplier=2.0, max_backoff_ms=60000, max_cycles=3, execution_history_limit=1000, agent_idle_timeout_seconds=300.0, agent_idle_drain_window_seconds=0.5, agent_idle_max_waiting_on_child_seconds=1800.0, agent_idle_poll_interval_seconds=0.05, agent_parent_exit_grace_seconds=5.0, agent_descendant_wait_timeout_seconds=30.0, agent_descendant_wait_poll_seconds=0.5, agent_process_exit_wait_seconds=30.0, agent_max_session_seconds=None, agent_waiting_status_interval_seconds=30.0, agent_suspect_waiting_on_child_seconds=600.0, agent_idle_no_progress_waiting_on_child_seconds=600.0, agent_child_progress_ttl_seconds=45.0, agent_child_heartbeat_ttl_seconds=15.0, agent_child_stale_label_ttl_seconds=10.0, agent_child_exit_reconcile_seconds=5.0)[source]¶

Bases: BaseModel

[general] section of ralph-workflow.toml.

Parameters:

verbosity (int)
workflow (GeneralWorkflowFlags)
developer_iters (Annotated[int, Ge(ge=1)])
developer_context (Annotated[int, Ge(ge=1)])
prompt_path (Path | None)
templates_dir (Path | None)
git_user_name (str | None)
git_user_email (str | None)
provider_fallback (dict[str, list[str]])
max_same_agent_retries (Annotated[int, Ge(ge=0)])
max_commit_residual_retries (Annotated[int, Ge(ge=0)])
max_retries (Annotated[int, Ge(ge=0)])
retry_delay_ms (Annotated[int, Ge(ge=0)])
backoff_multiplier (Annotated[float, Ge(ge=1.0)])
max_backoff_ms (Annotated[int, Ge(ge=0)])
max_cycles (Annotated[int, Ge(ge=1)])
execution_history_limit (Annotated[int, Ge(ge=1)])
agent_idle_timeout_seconds (Annotated[float, Gt(gt=0)])
agent_idle_drain_window_seconds (Annotated[float, Ge(ge=0)])
agent_idle_max_waiting_on_child_seconds (Annotated[float, Gt(gt=0)])
agent_idle_poll_interval_seconds (Annotated[float, Gt(gt=0)])
agent_parent_exit_grace_seconds (Annotated[float, Ge(ge=0)])
agent_descendant_wait_timeout_seconds (Annotated[float, Ge(ge=0)])
agent_descendant_wait_poll_seconds (Annotated[float, Gt(gt=0)])
agent_process_exit_wait_seconds (Annotated[float, Ge(ge=0)])
agent_max_session_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_waiting_status_interval_seconds (Annotated[float, Gt(gt=0)])
agent_suspect_waiting_on_child_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_idle_no_progress_waiting_on_child_seconds (Annotated[float | None, Gt(gt=0.0)])
agent_child_progress_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_heartbeat_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_stale_label_ttl_seconds (Annotated[float, Gt(gt=0)])
agent_child_exit_reconcile_seconds (Annotated[float, Ge(ge=0)])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.config.general_config.GeneralWorkflowFlags(*, checkpoint_enabled=True)[source]¶

Bases: BaseModel

General configuration workflow automation flags.

Parameters:: checkpoint_enabled (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.json_parser_type¶

JSON parser type enum for agent output parsing.

class ralph.config.json_parser_type.JsonParserType(*values)[source]¶

Bases: StrEnum

JSON parser type for agent output parsing.

CLAUDE¶: Parser for Claude’s NDJSON streaming format

CODEX¶: Parser for Codex’s NDJSON streaming format

GEMINI¶: Parser for Gemini’s NDJSON streaming format

OPENCODE¶: Parser for OpenCode’s NDJSON streaming format

GENERIC¶: Generic NDJSON parser for other agents

ralph.config.mcp_server_spec¶

MCP server configuration model for mcp.toml.

class ralph.config.mcp_server_spec.McpServerSpec(*, name, transport, url=None, command=None, args=<factory>, env=<factory>, chains=None)[source]¶

Bases: BaseModel

Schema for a single MCP server entry in mcp.toml.

Parameters:

name (Annotated[str, _PydanticGeneralMetadata(pattern='^[a-z][a-z0-9_-]*$')])
transport (Literal['http', 'stdio'])
url (str | None)
command (str | None)
args (list[str])
env (dict[str, str])
chains (list[str] | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.pause_on_exit¶

Pause behavior enum for process exit.

class ralph.config.pause_on_exit.PauseOnExit(*values)[source]¶

Bases: StrEnum

Pause behavior before process exit.

AUTO¶: Pause only on standalone failure

ALWAYS¶: Always pause before exit

NEVER¶: Never pause before exit

ralph.config.prompt_helper_config¶

Prompt helper configuration.

class ralph.config.prompt_helper_config.PromptHelperConfig(*, agent=None)[source]¶

Bases: BaseModel

Configuration for the prompt helper feature.

Parameters:: agent (str | None)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.recovery_strategy¶

Recovery strategy enum for pipeline failures.

class ralph.config.recovery_strategy.RecoveryStrategy(*values)[source]¶

Bases: StrEnum

Recovery strategy when pipeline encounters failures.

FAIL¶: Fail immediately on errors

AUTO¶: Attempt automatic recovery

FORCE¶: Force through errors

ralph.config.verbosity¶

Verbosity level enum for Ralph output.

class ralph.config.verbosity.Verbosity(*values)[source]¶

Bases: StrEnum

Verbosity level for Ralph output.

QUIET¶: Minimal output (errors only)

NORMAL¶: Default verbosity level

VERBOSE¶: More detailed output

FULL¶: Full output with all details

DEBUG¶: Debug-level output for troubleshooting

ralph.config.web_search_config¶

Web search configuration models for mcp.toml.

class ralph.config.web_search_config.WebSearchConfig(*, enabled=True, backend='ddgs', fallback=<factory>, backends=<factory>)[source]¶

Bases: BaseModel

Top-level web_search config in mcp.toml.

Parameters:

enabled (bool)
backend (str)
fallback (list[str])
backends (dict[str, WebSearchBackendSpec])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.config.web_service_configs¶

Web visit and media configuration models for mcp.toml.

class ralph.config.web_service_configs.WebVisitConfig(*, enabled=True, timeout_ms=15000, max_bytes=2097152, user_agent='RalphWorkflow/1.0 (+https://ralph-workflow.dev)', allow_private_networks=False, extract_links=False)[source]¶

Bases: BaseModel

Top-level web_visit config in mcp.toml.

Parameters:

enabled (bool)
timeout_ms (Annotated[int, Gt(gt=0)])
max_bytes (Annotated[int, Gt(gt=0)])
user_agent (str)
allow_private_networks (bool)
extract_links (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Policy¶

ralph.policy¶

Policy module for Ralph orchestration configuration.

This module provides the policy layer that drives Ralph’s configurable orchestration. Policy is expressed in three TOML files:

agents.toml: Agent chains and drain-to-chain bindings
pipeline.toml: Phase graph and transition routing
artifacts.toml: Artifact contracts per drain

The loader validates all three files together, ensuring cross-file consistency (e.g., every drain used in pipeline.toml is bound in agents.toml).

Example usage:

from pathlib import Path
from ralph.policy import load_policy

bundle = load_policy(Path(".agent"))
drain_binding = bundle.agents.agent_drains["planning"]
chain = bundle.agents.agent_chains[drain_binding.chain]

ralph.policy.loader¶

TOML policy loader with fallback to bundled defaults.

Loads agents.toml, pipeline.toml, and artifacts.toml from the user’s .agent/ config directory, falling back to the packaged defaults when files are absent.

All loading goes through Pydantic validation so any malformed config surfaces as a PolicyValidationError with field-level detail.

User-global policy overrides prefer branded filenames (ralph-workflow-pipeline.toml, ralph-workflow-artifacts.toml) while still accepting the legacy unprefixed names for backward compatibility.

ralph.policy.loader.load_policy(config_dir, config=None)[source]¶

Load all three policy TOML files and return a validated PolicyBundle.

Files are loaded from config_dir (the .agent/ directory). Any absent file is silently replaced with the bundled default.

Parameters:

config_dir (Path)
config (UnifiedConfig | None)

Return type:

PolicyBundle

ralph.policy.loader.load_policy_or_die(config_dir, config=None)[source]¶

Load policy, exiting with a user-friendly message on failure.

Parameters:

config_dir (Path) – Path to the .agent/ configuration directory.
config (UnifiedConfig | None)

Returns:

Validated PolicyBundle.

Return type:

PolicyBundle

ralph.policy.models¶

Pydantic models for policy configuration (agents.toml, pipeline.toml, artifacts.toml).

class ralph.policy.models.AgentChainConfig(*, agents, max_retries=3, retry_delay_ms=1000)[source]¶

Bases: _FrozenPolicyModel

Definition of a named agent fallback chain.

Parameters:

agents (Annotated[list[str], MinLen(min_length=1)])
max_retries (Annotated[int, Ge(ge=0)])
retry_delay_ms (Annotated[int, Ge(ge=0)])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.AgentDrainConfig(*, chain, drain_class=None, capability_class=None)[source]¶

Bases: _FrozenPolicyModel

Binding from a named drain to an agent chain.

Parameters:

chain (str)
drain_class (str | None)
capability_class (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.AgentsPolicy(*, agent_chains=<factory>, agent_drains=<factory>, forbid_sibling_drain_inference=False)[source]¶

Bases: _FrozenPolicyModel

Top-level agents.toml policy document.

Parameters:

agent_chains (dict[str, AgentChainConfig])
agent_drains (dict[str, AgentDrainConfig])
forbid_sibling_drain_inference (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.ArtifactContract(*, drain, artifact_type, decision_vocabulary=<factory>, prompt_template=None, artifact_json_path=None, markdown_summary_path=None)[source]¶

Bases: _FrozenPolicyModel

Contract for an artifact type submitted by an agent at a given drain.

Parameters:

drain (str)
artifact_type (str)
decision_vocabulary (list[str])
prompt_template (str | None)
artifact_json_path (str | None)
markdown_summary_path (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.ArtifactHistoryPolicy(*, enabled=False, clear_on_fresh_entry=True)[source]¶

Bases: _FrozenPolicyModel

Per-phase artifact history policy.

Parameters:

enabled (bool)
clear_on_fresh_entry (bool)

model_config = {'extra': 'forbid', 'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.ArtifactProofPolicy(*, require_plan_proof=True, require_analysis_proof=True)[source]¶

Bases: _FrozenPolicyModel

Per-phase proof requirements for development artifacts.

Parameters:

require_plan_proof (bool)
require_analysis_proof (bool)

model_config = {'extra': 'forbid', 'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.ArtifactsPolicy(*, artifacts=<factory>)[source]¶

Bases: _FrozenPolicyModel

Top-level artifacts.toml policy document.

Parameters:: artifacts (dict[str, ArtifactContract])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.BudgetCounterConfig(*, description='', tracks_budget=True, default_max)[source]¶

Bases: _FrozenPolicyModel

Declaration of a named budget counter in the pipeline.

Parameters:

description (str)
tracks_budget (bool)
default_max (Annotated[int, Ge(ge=0)])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.policy.models.DrainName¶: alias of str

class ralph.policy.models.GroupPolicyBlock(*, kind='group', child_blocks=<factory>, completion_block, before_complete=<factory>, after_complete=<factory>, increments_counter=None, loop_resets=<factory>)[source]¶

Bases: _FrozenPolicyModel

Composite authoring block that owns lifecycle semantics.

Parameters:

kind (Literal['group'])
child_blocks (list[str])
completion_block (str)
before_complete (list[str])
after_complete (list[str])
increments_counter (str | None)
loop_resets (list[str])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.IndividualPolicyBlock(*, kind='individual', phase_name, phase)[source]¶

Bases: _FrozenPolicyModel

Leaf authoring block that compiles directly to one runtime phase.

Parameters:

kind (Literal['individual'])
phase_name (str)
phase (PhaseDefinition)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.LifecyclePhasePolicy(*, lifecycle_name, completion_block, increments_counter=None, loop_resets=<factory>, before_complete=<factory>, after_complete=<factory>)[source]¶

Bases: _FrozenPolicyModel

Lifecycle-owned accounting metadata keyed by compiled completion phase.

Parameters:

lifecycle_name (str)
completion_block (str)
increments_counter (str | None)
loop_resets (list[str])
before_complete (list[str])
after_complete (list[str])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.LoopCounterConfig(*, default_max=3, description='')[source]¶

Bases: _FrozenPolicyModel

Declaration of a named loop iteration counter in the pipeline.

Parameters:

default_max (Annotated[int, Ge(ge=0)])
description (str)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseCommitPolicy(*, requires_artifact=True, skipped_advances_progress=True, increments_counter=None, route_counter=None, loop_resets=<factory>)[source]¶

Bases: _FrozenPolicyModel

Commit semantics for commit-role phases.

Parameters:

requires_artifact (bool)
skipped_advances_progress (bool)
increments_counter (str | None)
route_counter (str | None)
loop_resets (list[str])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseDecisionRoute(*, target, reset_loop=False, increments_counter=None)[source]¶

Bases: _FrozenPolicyModel

Route produced by an analysis decision.

Parameters:

target (str)
reset_loop (bool)
increments_counter (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseDefinition(*, drain, transitions, role=None, skip_invocation=False, retry_policy=None, loop_policy=None, decisions=<factory>, commit_policy=None, verification=None, artifact_required=True, terminal_outcome=None, bypass_routes=<factory>, clean_outcome=None, issues_outcome=None, prompt_template=None, continuation_template=None, loopback_prompt_template=None, parallelization=None, artifact_history=None, artifact_proof_policy=None, workflow_fallback=None, clear_drains_on_fresh_entry=<factory>, display_style=None)[source]¶

Bases: _FrozenPolicyModel

Definition of a single phase in the pipeline graph.

Parameters:

drain (str)
transitions (PhaseTransition)
role (Literal['execution', 'analysis', 'review', 'commit', 'verification', 'terminal', 'fanout_join', 'commit_cleanup'] | None)
skip_invocation (bool)
retry_policy (PhaseRetryPolicy | None)
loop_policy (PhaseLoopPolicy | None)
decisions (dict[str, PhaseDecisionRoute])
commit_policy (PhaseCommitPolicy | None)
verification (PhaseVerificationPolicy | None)
artifact_required (bool)
terminal_outcome (Literal['success', 'failure'] | None)
bypass_routes (dict[str, str])
clean_outcome (str | None)
issues_outcome (str | None)
prompt_template (str | None)
continuation_template (str | None)
loopback_prompt_template (str | None)
parallelization (PhaseParallelization | None)
artifact_history (ArtifactHistoryPolicy | None)
artifact_proof_policy (ArtifactProofPolicy | None)
workflow_fallback (PhaseWorkflowFallback | None)
clear_drains_on_fresh_entry (list[str])
display_style (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseLoopPolicy(*, iteration_state_field, loopback_review_outcome=None)[source]¶

Bases: _FrozenPolicyModel

Loop linkage for analysis phases.

Parameters:

iteration_state_field (str)
loopback_review_outcome (str | None)

model_config = {'extra': 'forbid', 'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseParallelization(*, mode='same_workspace', max_parallel_workers=8, max_work_units=50, require_allowed_directories=True, post_fanout_verification=False)[source]¶

Bases: _FrozenPolicyModel

Transition-scoped parallelization policy for a pipeline phase.

Parameters:

mode (Literal['same_workspace'])
max_parallel_workers (Annotated[int, Ge(ge=1)])
max_work_units (Annotated[int, Ge(ge=1)])
require_allowed_directories (bool)
post_fanout_verification (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseRetryPolicy(*, max_retries=3, retry_delay_ms=1000, retry_in_session=False)[source]¶

Bases: _FrozenPolicyModel

Per-phase retry policy overriding chain-level defaults.

Parameters:

max_retries (Annotated[int, Ge(ge=0)])
retry_delay_ms (Annotated[int, Ge(ge=0)])
retry_in_session (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseTransition(*, on_success, on_failure=None, on_loopback=None)[source]¶

Bases: _FrozenPolicyModel

Transition rules from a phase to other phases.

Parameters:

on_success (str)
on_failure (str | None)
on_loopback (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseVerificationPolicy(*, kind, gate_for, on_failure_route=None)[source]¶

Bases: _FrozenPolicyModel

Verification gating semantics for a phase.

Parameters:

kind (Literal['artifact', 'none'])
gate_for (Literal['advancement', 'completion', 'release'])
on_failure_route (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PhaseWorkflowFallback(*, target, note=None)[source]¶

Bases: _FrozenPolicyModel

Policy-declared workflow-level fallback when a phase’s agent chain is exhausted.

Parameters:

target (str)
note (str | None)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PipelinePolicy(*, blocks=<factory>, phases=<factory>, entry_block=None, entry_phase='planning', terminal_phase='complete', loop_counters=<factory>, budget_counters=<factory>, post_commit_routes=<factory>, lifecycle_phases=<factory>, default_phase_retry_policy=<factory>, recovery=<factory>)[source]¶

Bases: _FrozenPolicyModel

Top-level pipeline.toml policy document.

Parameters:

blocks (dict[str, PolicyBlock])
phases (dict[str, PhaseDefinition])
entry_block (str | None)
entry_phase (str)
terminal_phase (str)
loop_counters (dict[str, LoopCounterConfig])
budget_counters (dict[str, BudgetCounterConfig])
post_commit_routes (list[PostCommitRoute])
lifecycle_phases (dict[str, LifecyclePhasePolicy])
default_phase_retry_policy (PhaseRetryPolicy)
recovery (RecoveryPolicy)

effective_retry_policy(phase_name)[source]¶

Resolve the effective retry policy for a phase.

Parameters:: phase_name (str)
Return type:: PhaseRetryPolicy

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

terminal_states()[source]¶

Return the full set of terminal state names for transition validation.

Return type:: set[str]

class ralph.policy.models.PolicyBundle(*, agents, pipeline, artifacts)[source]¶

Bases: _FrozenPolicyModel

Aggregate of all three policy documents.

Parameters:

agents (AgentsPolicy)
pipeline (PipelinePolicy)
artifacts (ArtifactsPolicy)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PostCommitRoute(*, when, target)[source]¶

Bases: _FrozenPolicyModel

Budget-guarded route applied after commit success.

Parameters:

when (PostCommitRouteWhen)
target (str)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.PostCommitRouteWhen(*, phase, budget_state)[source]¶

Bases: _FrozenPolicyModel

Condition selector for post-commit budget-guarded routing.

Parameters:

phase (str)
budget_state (Literal['remaining', 'exhausted', 'no_review'])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.policy.models.RecoveryPolicy(*, cycle_cap=200, failed_route='failed_terminal', terminal_failure_phase=None, preserve_session_on_categories=('agent',))[source]¶

Bases: _FrozenPolicyModel

Pipeline-wide recovery policy.

Parameters:

cycle_cap (Annotated[int, Ge(ge=1)])
failed_route (str)
terminal_failure_phase (str | None)
preserve_session_on_categories (tuple[str, ...])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.policy.validation¶

Policy validation utilities beyond what Pydantic provides at the model level.

exception ralph.policy.validation.CheckpointPolicyMismatchError(checkpoint_phase, valid_phases)[source]¶

Bases: Exception

Raised when a checkpoint’s phase is not present in the current policy.

Parameters:

checkpoint_phase (str)
valid_phases (set[str])

Return type:

None

checkpoint_phase¶: Phase name stored in the checkpoint.

valid_phases¶: Set of valid phase names in the current policy.

exception ralph.policy.validation.PolicyValidationError(message, source=None)[source]¶

Bases: Exception

Raised when a policy validation rule is violated.

Parameters:

message (str)
source (str | None)

Return type:

None

message¶: Human-readable error message describing the validation failure.

source¶: Which policy area failed (optional).

ralph.policy.validation.get_drain_resolution_matrix(bundle)[source]¶

Generate a normalized drain resolution matrix.

Parameters:: bundle (PolicyBundle)
Return type:: dict[str, dict[str, str]]

ralph.policy.validation.validate_agent_chains_satisfiable(bundle, agent_registry)[source]¶

Validate that every agent referenced in every chain exists in the registry.

Parameters:

bundle (PolicyBundle)
agent_registry (AgentRegistry)

Return type:

None

ralph.policy.validation.validate_chain_exists(chain, bundle)[source]¶

Validate that an agent chain is defined.

Parameters:

chain (str)
bundle (PolicyBundle)

Return type:

None

ralph.policy.validation.validate_checkpoint_against_policy(state, bundle)[source]¶

Validate a checkpoint state against the current policy bundle.

Parameters:

state (PipelineState)
bundle (PolicyBundle)

Return type:

None

ralph.policy.validation.validate_checkpoint_compatible(checkpoint_phase, bundle)[source]¶

Validate that a checkpoint phase is compatible with the current policy bundle.

Parameters:

checkpoint_phase (str)
bundle (PolicyBundle)

Return type:

None

ralph.policy.validation.validate_cli_counter_overrides(policy, cli_counter_overrides, errors)[source]¶

Validate that every CLI counter override names a declared budget counter.

Parameters:

policy (PipelinePolicy)
cli_counter_overrides (dict[str, int])
errors (list[str])

Return type:

None

ralph.policy.validation.validate_drain_bound(drain, bundle)[source]¶

Validate that a drain name has a binding in the current policy.

Parameters:

drain (str)
bundle (PolicyBundle)

Return type:

None

ralph.policy.validation.validate_drain_contracts(bundle)[source]¶

Validate drain contracts and enforce strict binding rules.

Parameters:: bundle (PolicyBundle)
Return type:: None

ralph.policy.validation.validate_phase_exists_in_policy(phase, policy)[source]¶

Validate that a phase name is present in the current pipeline policy.

Parameters:

phase (str)
policy (PipelinePolicy)

Return type:

None

ralph.policy.validation.validate_policy_completeness(bundle, *, cli_counter_overrides=None)[source]¶

Validate that the policy bundle is semantically complete for policy-driven orchestration.

Parameters:

bundle (PolicyBundle)
cli_counter_overrides (dict[str, int] | None)

Return type:

None

ralph.policy.validation.validate_recovery_config(bundle)[source]¶

Validate recovery-related configuration in the policy bundle.

Parameters:: bundle (PolicyBundle)
Return type:: None

ralph.policy.validation.validate_required_inputs(workspace_scope, inline_prompt=None)[source]¶

Validate that required input files exist and are readable.

Parameters:

workspace_scope (WorkspaceScope)
inline_prompt (str | None)

Return type:

None

ralph.policy.validation.validate_work_units_against_policy(work_units, pipeline_policy, *, phase)[source]¶

Validate parsed planning work_units against the active phase’s parallelization policy.

Parameters:

work_units (WorkUnitsPlan)
pipeline_policy (PipelinePolicy)
phase (str)

Return type:

None

ralph.policy.explain¶

Policy explanation — converts a PolicyBundle into a structured human-readable description.

This package answers the key questions a user has when looking at an unfamiliar policy: - What happens after this phase succeeds? - What makes a phase terminal? - When is a commit required? - When does the system retry vs fall back vs fail? - When is parallel execution allowed?

ralph.policy.explain.budget_counter_explanation¶

Explanation of a budget counter.

class ralph.policy.explain.budget_counter_explanation.BudgetCounterExplanation(name, description, tracks_budget, default_max=0)[source]¶

Bases: object

Explanation of a budget counter.

Parameters:

name (str)
description (str)
tracks_budget (bool)
default_max (int)

ralph.policy.explain.commit_policy_explanation¶

Explanation of a phase’s commit policy.

class ralph.policy.explain.commit_policy_explanation.CommitPolicyExplanation(increments_counter, loop_resets, requires_artifact)[source]¶

Bases: object

Explanation of a phase’s commit policy.

Parameters:

increments_counter (str | None)
loop_resets (list[str])
requires_artifact (bool)

ralph.policy.explain.loop_counter_explanation¶

Explanation of a loop counter.

class ralph.policy.explain.loop_counter_explanation.LoopCounterExplanation(name, default_max, description)[source]¶

Bases: object

Explanation of a loop counter.

Parameters:

name (str)
default_max (int)
description (str)

ralph.policy.explain.lifecycle_explanation¶

Lifecycle completion explanation structures.

class ralph.policy.explain.lifecycle_explanation.LifecycleExplanation(lifecycle_name, completion_phase, completion_block, increments_counter=None, before_complete=<factory>, after_complete=<factory>)[source]¶

Bases: object

Human-readable lifecycle completion metadata.

Parameters:

lifecycle_name (str)
completion_phase (str)
completion_block (str)
increments_counter (str | None)
before_complete (list[str])
after_complete (list[str])

ralph.policy.explain.loop_policy_explanation¶

Explanation of a phase’s loop policy.

class ralph.policy.explain.loop_policy_explanation.LoopPolicyExplanation(max_iterations, iteration_state_field, loopback_review_outcome)[source]¶

Bases: object

Explanation of a phase’s loop policy.

Parameters:

max_iterations (int)
iteration_state_field (str)
loopback_review_outcome (str | None)

ralph.policy.explain.parallel_explanation¶

Explanation of the parallel execution policy.

class ralph.policy.explain.parallel_explanation.ParallelExplanation(phase, max_parallel_workers, max_work_units, require_allowed_directories, post_fanout_verification=False)[source]¶

Bases: object

Explanation of the parallel execution policy.

Parameters:

phase (str)
max_parallel_workers (int)
max_work_units (int)
require_allowed_directories (bool)
post_fanout_verification (bool)

ralph.policy.explain.phase_explanation¶

Explanation of a single phase.

class ralph.policy.explain.phase_explanation.PhaseExplanation(name, role, drain, chain, agents, max_retries, skip_invocation, on_success, on_failure, on_loopback, bypass_routes, decisions, loop_policy, commit_policy, terminal_outcome, clean_outcome=None, issues_outcome=None, is_entry=False, is_terminal=False, verification=None, has_parallelization=False, post_commit_routes_info=<factory>, workflow_fallback=None)[source]¶

Bases: object

Explanation of a single phase.

Parameters:

name (str)
role (str | None)
drain (str)
chain (str | None)
agents (list[str])
max_retries (int)
skip_invocation (bool)
on_success (str | None)
on_failure (str | None)
on_loopback (str | None)
bypass_routes (dict[str, str])
decisions (dict[str, str])
loop_policy (LoopPolicyExplanation | None)
commit_policy (CommitPolicyExplanation | None)
terminal_outcome (str | None)
clean_outcome (str | None)
issues_outcome (str | None)
is_entry (bool)
is_terminal (bool)
verification (VerificationExplanation | None)
has_parallelization (bool)
post_commit_routes_info (list[tuple[str, str]])
workflow_fallback (tuple[str, str | None] | None)

ralph.policy.explain.policy_explanation¶

Complete structured explanation of a PolicyBundle.

class ralph.policy.explain.policy_explanation.PolicyExplanation(entry_phase, terminal_phase, entry_block=None, authored_blocks=<factory>, lifecycle_explanations=<factory>, phases=<factory>, loop_counters=<factory>, budget_counters=<factory>, terminal_outcomes=<factory>, parallel_execution=None, parallel_executions=<factory>, post_commit_routes=<factory>, recovery=None)[source]¶

Bases: object

Complete structured explanation of a PolicyBundle.

Parameters:

entry_phase (str)
terminal_phase (str)
entry_block (str | None)
authored_blocks (list[str])
lifecycle_explanations (list[LifecycleExplanation])
phases (list[PhaseExplanation])
loop_counters (list[LoopCounterExplanation])
budget_counters (list[BudgetCounterExplanation])
terminal_outcomes (list[TerminalOutcomeExplanation])
parallel_execution (ParallelExplanation | None)
parallel_executions (list[ParallelExplanation])
post_commit_routes (list[PostCommitRouteExplanation])
recovery (RecoveryExplanation | None)

ralph.policy.explain.post_commit_route_explanation¶

Explanation of a single post-commit route entry.

class ralph.policy.explain.post_commit_route_explanation.PostCommitRouteExplanation(phase, budget_state, target)[source]¶

Bases: object

Explanation of a single post-commit route entry.

Parameters:

phase (str)
budget_state (str)
target (str)

ralph.policy.explain.recovery_explanation¶

Explanation of the recovery policy.

class ralph.policy.explain.recovery_explanation.RecoveryExplanation(cycle_cap, terminal_recovery_route, preserve_session_on_categories)[source]¶

Bases: object

Explanation of the recovery policy.

Parameters:

cycle_cap (int)
terminal_recovery_route (str)
preserve_session_on_categories (list[str])

ralph.policy.explain.terminal_outcome_explanation¶

Explanation of a terminal phase outcome.

class ralph.policy.explain.terminal_outcome_explanation.TerminalOutcomeExplanation(phase, outcome)[source]¶

Bases: object

Explanation of a terminal phase outcome.

Parameters:

phase (str)
outcome (str)

ralph.policy.explain.verification_explanation¶

Explanation of a phase’s verification policy.

class ralph.policy.explain.verification_explanation.VerificationExplanation(kind, gate_for, on_failure_route)[source]¶

Bases: object

Explanation of a phase’s verification policy.

Parameters:

kind (str)
gate_for (str)
on_failure_route (str | None)

ralph.policy.render¶

Render a PolicyExplanation as human-readable text or ASCII workflow diagram.

This module converts the structured PolicyExplanation dataclass (from explain.py) into text or rich console output that answers: - What happens after this phase succeeds? - What makes a phase terminal? - When is a commit required? - When does the system retry vs fall back vs fail? - When is parallel execution allowed?

ralph.policy.render.render_explanation_ascii(exp)[source]¶

Render a PolicyExplanation as a deterministic pure-ASCII workflow diagram.

Visual contract (per PLAN step 4):

BOX STRUCTURE: Each phase renders as a 4-line box: Line 1: “+” + “-” * (width-2) + “+” Line 2: “|” + <phase_name> centered + “|” Line 3: “|” + “role=<role>” centered + “|” Line 4: “+” + “-” * (width-2) + “+” Width = max(len(name), len(“role=” + role), 6) + 4
ENTRY MARKER: =ENTRY=> appears on the line above the entry phase box.
HAPPY-PATH: A center-aligned “|” then “v” arrowhead connects consecutive phases on the success spine.
DECISION BRANCHES: For each decision whose target differs from on_success, render “ +–[decision_name]–> target_phase” (4-space indent).
LOOPBACK: When on_loopback differs from on_success, render “ <<==[loopback]== returns to ‘target_phase’” When loop_policy is set, also render: “ [LOOPBACK: counter=NAME, max=N]” And always append the re-entry banner: “ >> RE-ENTRY at target_phase”
TERMINAL MARKERS: ==SUCCESS==> for terminal_outcome=”success”; ==FAILURE==> for terminal_outcome=”failure”. Only policy-declared terminal phases get markers.
FANOUT ANNOTATION: >>> FAN_OUT (max_workers=N, max_units=M, post_fanout_verify=yes/no) appears above the phase box for the parallel-eligible phase.
LOOP ANNOTATION: [loop: counter=NAME, max=N] appears above the phase box for phases with loop_policy.
GLYPHS: Pure ASCII only — allowed chars: + - | < > v ^ = [ ] _ . , plus alphanumerics. No Unicode box-drawing characters.
ORDERING: Success spine (follows on_success from entry_phase); unvisited phases appended alphabetically. Ties broken alphabetically.

Parameters:: exp (PolicyExplanation) – The policy explanation to render.
Returns:: A multi-line ASCII string representing the workflow diagram.
Return type:: str

ralph.policy.render.render_explanation_sentences(phase)[source]¶

Generate explanation sentences for a phase per Required Product Outcome D.

Parameters:: phase (PhaseExplanation)
Return type:: list[str]

ralph.policy.render.render_explanation_text(exp)[source]¶

Render a PolicyExplanation as a multi-section human-readable text string.

Parameters:: exp (object)
Return type:: str

Pipeline¶

ralph.pipeline¶

Public pipeline state and reducer exports.

This package is the core of Ralph’s orchestration loop. It exposes the public state/event types most callers need, plus the pure reduce function used to advance the state machine.

ralph.pipeline.checkpoint¶

Atomic checkpoint persistence for pipeline resume.

This module handles saving and loading pipeline state checkpoints. Checkpoints enable the pipeline to resume from interruption without losing progress.

All writes are atomic (write to .tmp then rename) to prevent partial checkpoint corruption.

class ralph.pipeline.checkpoint.Checkpoint(path=PosixPath('.agent/checkpoint.json'))[source]¶

Bases: object

Handle for atomic checkpoint read/write operations at a fixed path.

Parameters:: path (Path)

ralph.pipeline.checkpoint.exists(path=PosixPath('.agent/checkpoint.json'))[source]¶

Check if a checkpoint exists.

Parameters:: path (Path) – Path to the checkpoint file.
Returns:: True if checkpoint exists.
Return type:: bool

ralph.pipeline.checkpoint.inspect(path=PosixPath('.agent/checkpoint.json'))[source]¶

Return formatted checkpoint summary.

Parameters:: path (Path) – Path to the checkpoint file.
Returns:: Formatted string representation of the checkpoint.
Return type:: str

ralph.pipeline.checkpoint.load(path=PosixPath('.agent/checkpoint.json'))[source]¶

Load checkpoint from disk.

Parameters:: path (Path) – Path to the checkpoint file.
Returns:: PipelineState if checkpoint exists and is valid, None otherwise. If the loaded state contains a forbidden last_error sentinel (e.g. “Unknown failure”), it is dropped and replaced with None.
Return type:: PipelineState | None

async ralph.pipeline.checkpoint.load_async(path=PosixPath('.agent/checkpoint.json'))[source]¶

Load checkpoint from disk without blocking the event loop.

Delegates to load() via asyncio.to_thread so callers can await this from an async context without stalling the event loop.

Parameters:: path (Path) – Path to the checkpoint file.
Returns:: PipelineState if checkpoint exists and is valid, None otherwise.
Return type:: PipelineState | None

ralph.pipeline.checkpoint.remove(path=PosixPath('.agent/checkpoint.json'))[source]¶

Remove a checkpoint file.

Parameters:: path (Path) – Path to the checkpoint file.
Return type:: None

ralph.pipeline.checkpoint.save(state, path=PosixPath('.agent/checkpoint.json'))[source]¶

Atomically write state to disk.

Writes to a temporary file first, then renames to the target path. This ensures no partial checkpoint data on disk if the write is interrupted.

Parameters:

state (PipelineState) – The pipeline state to save.
path (Path) – Path to save the checkpoint. Defaults to .agent/checkpoint.json.

Return type:

None

async ralph.pipeline.checkpoint.save_async(state, path=PosixPath('.agent/checkpoint.json'))[source]¶

Atomically write state to disk without blocking the event loop.

Delegates to save() via asyncio.to_thread so callers can await this from an async context without stalling the event loop.

Parameters:

state (PipelineState) – The pipeline state to save.
path (Path) – Path to save the checkpoint. Defaults to .agent/checkpoint.json.

Return type:

None

ralph.pipeline.checkpoint.worker_checkpoint_path(worker_namespace)[source]¶

Return the worker-local checkpoint path.

Parameters:: worker_namespace (Path)
Return type:: Path

ralph.pipeline.cycle_baseline¶

Development-cycle diff baseline management.

The baseline SHA is written once when a dev cycle begins (after planning succeeds, before any development phase invocation) and is never updated by mid-cycle commits. It is cleared at cycle boundaries so that the next cycle starts fresh.

ralph.pipeline.cycle_baseline.clear_cycle_baseline(workspace_root)[source]¶

Remove the baseline file so the next cycle starts fresh.

Parameters:: workspace_root (Path)
Return type:: None

ralph.pipeline.cycle_baseline.read_cycle_baseline(workspace_root)[source]¶

Return the recorded baseline SHA, or None if no baseline is set.

Parameters:: workspace_root (Path)
Return type:: str | None

ralph.pipeline.cycle_baseline.write_cycle_baseline(workspace_root, sha, *, force=False)[source]¶

Record sha as the diff baseline for the current dev cycle.

When force is False (the default), an existing baseline is preserved and this call is a no-op. Callers that open a fresh cycle must pass force=True to overwrite any stale baseline.

Parameters:

workspace_root (Path)
sha (str)
force (bool)

Return type:

None

ralph.pipeline.effects¶

Effect types: what the pipeline wants to do next.

Effects are emitted by the orchestrator and describe the next action to be taken. They carry all necessary data for the effect handler to execute the action.

No I/O is performed in this module - effects are pure data descriptions.

ralph.pipeline.effects.commit_effect¶

Commit pipeline effect.

class ralph.pipeline.effects.commit_effect.CommitEffect(message_file)[source]¶

Bases: object

Effect to create a git commit.

Parameters:: message_file (str)

message_file¶

Path to the commit message file.

Type:: str

ralph.pipeline.effects.early_skip_commit_effect¶

Early-skip-commit pipeline effect.

class ralph.pipeline.effects.early_skip_commit_effect.EarlySkipCommitEffect[source]¶

Bases: object

Effect to skip a commit phase before prompt materialization or agent invocation.

Emitted by the orchestrator when the worktree has no pending work so the commit phase can advance via COMMIT_SKIPPED without creating a commit prompt or invoking a commit agent.

ralph.pipeline.effects.exhausted_analysis_phase_advance_effect¶

Exhausted-analysis-phase-advance pipeline effect.

class ralph.pipeline.effects.exhausted_analysis_phase_advance_effect.ExhaustedAnalysisPhaseAdvanceEffect(phase)[source]¶

Bases: object

Effect to bypass an already exhausted analysis phase through PHASE_ADVANCE.

Used when the runner is already sitting in an exhausted analysis phase. The runner must not invoke the analysis agent again; instead it emits PHASE_ADVANCE so reducer-owned success routing, loop resets, and phase advancement remain the single source of truth.

Parameters:: phase (str)

ralph.pipeline.effects.exit_failure_effect¶

Exit-failure pipeline effect.

class ralph.pipeline.effects.exit_failure_effect.ExitFailureEffect(reason)[source]¶

Bases: object

Effect to exit with failure.

Parameters:: reason (str)

reason¶

Reason for the failure. Must be non-empty, non-whitespace, and must not contain any known non-empty sentinel that indicates a bug (e.g. “Unknown failure”, “None”, “null”). Empty and whitespace-only reasons are rejected separately. Sentinel checks are performed as substring matches to catch cases like “development: Unknown failure”.

Type:: str

ralph.pipeline.effects.exit_success_effect¶

Exit-success pipeline effect.

class ralph.pipeline.effects.exit_success_effect.ExitSuccessEffect[source]¶

Bases: object

Effect to exit with success.

ralph.pipeline.effects.fan_out_effect¶

Fan-out pipeline effect.

class ralph.pipeline.effects.fan_out_effect.FanOutEffect(work_units, max_workers, run_post_fanout_verification=False, phase='')[source]¶

Bases: object

Effect to fan out parallel work for any phase whose [parallelization] policy is declared.

Workers run in the shared checkout. Each worker is restricted to its declared allowed_directories and writes its outputs to a per-worker namespace under .agent/workers/<unit_id>/.

Parameters:

work_units (tuple[WorkUnit, ...])
max_workers (int)
run_post_fanout_verification (bool)
phase (str)

work_units¶

Work units to execute in parallel.

Type:: tuple[ralph.pipeline.work_unit.WorkUnit, …]

max_workers¶

Maximum number of concurrent workers.

Type:: int

run_post_fanout_verification¶

When True, the runner will execute a serialized workspace-wide verification step after all workers finish. Defaults to False so unit tests do not invoke make verify.

Type:: bool

phase¶

The pipeline phase for which fan-out is occurring. Defaults to empty string for backward compatibility; the runner always populates this.

Type:: str

ralph.pipeline.effects.invoke_agent_effect¶

Invoke-agent pipeline effect.

class ralph.pipeline.effects.invoke_agent_effect.InvokeAgentEffect(agent_name, phase, prompt_file, drain=None, chain_name='')[source]¶

Bases: object

Effect to invoke an AI agent.

Parameters:

agent_name (str)
phase (str)
prompt_file (str)
drain (str | None)
chain_name (str)

agent_name¶

Name of the agent to invoke.

Type:: str

phase¶

Current pipeline phase.

Type:: str

prompt_file¶

Path to the prompt file for the agent.

Type:: str

chain_name¶

Name of the agent chain being used.

Type:: str

ralph.pipeline.effects.prepare_prompt_effect¶

Prepare-prompt pipeline effect.

class ralph.pipeline.effects.prepare_prompt_effect.PreparePromptEffect(phase, iteration=None, drain=None, previous_phase=None, skip_materialization=False)[source]¶

Bases: object

Effect to prepare a prompt for an agent.

Parameters:

phase (str)
iteration (int | None)
drain (str | None)
previous_phase (str | None)
skip_materialization (bool)

phase¶

Current pipeline phase.

Type:: str

iteration¶

Deprecated — kept for prompt-template rendering only; None when not applicable.

Type:: int | None

skip_materialization¶

When True, advance phase without materializing the prompt. Used for routing-only transitions (e.g. skip_invocation phases).

Type:: bool

ralph.pipeline.effects.push_effect¶

Push pipeline effect.

class ralph.pipeline.effects.push_effect.PushEffect(remote='origin', branch=None)[source]¶

Bases: object

Effect to push changes to remote.

Parameters:

remote (str)
branch (str | None)

remote¶

Remote name (default: origin).

Type:: str

branch¶

Branch name (optional, uses current branch if not specified).

Type:: str | None

ralph.pipeline.effects.save_checkpoint_effect¶

Save-checkpoint pipeline effect.

class ralph.pipeline.effects.save_checkpoint_effect.SaveCheckpointEffect[source]¶

Bases: object

Effect to save a checkpoint.

ralph.pipeline.events¶

Pipeline events representing all state transitions.

ralph.pipeline.events.analysis_decision_event¶

Analysis decision event for the pipeline.

class ralph.pipeline.events.analysis_decision_event.AnalysisDecisionEvent(phase, decision)[source]¶

Bases: object

Event emitted when an analysis phase resolves a decision from the agent artifact.

The reducer routes via policy.phases[phase].decisions[decision].target directly, making this a first-class routing input rather than a collapsed signal.

Parameters:

phase (str)
decision (str)

phase¶

Name of the phase that emitted this decision.

Type:: str

decision¶

Raw decision string from the agent artifact (validated against the phase’s decision_vocabulary in the artifacts policy).

Type:: str

ralph.pipeline.events.phase_failure_event¶

Phase failure event for the pipeline.

class ralph.pipeline.events.phase_failure_event.PhaseFailureEvent(phase, reason, recoverable, retry_in_session=False, failure_category=None)[source]¶

Bases: object

Event emitted when a phase handler encounters a failure condition.

This event carries a recoverable flag that determines how the reducer processes the failure: - recoverable=True: routes through _handle_agent_failure retry/fallback logic - recoverable=False: routes directly to the terminal failure phase

Parameters:

phase (str)
reason (str)
recoverable (bool)
retry_in_session (bool)
failure_category (FailureCategory | None)

phase¶

Name of the phase that generated this event.

Type:: str

reason¶

Human-readable description of what caused the failure.

Type:: str

recoverable¶

Whether this failure should trigger retry/fallback (True) or act as a terminal decision (False).

Type:: bool

retry_in_session¶

When True and the agent’s transport supports session resume, the recovery path should preserve the active session ID so the next retry continues in the same agent session rather than starting from scratch. Only meaningful when recoverable=True.

Type:: bool

failure_category¶

Optional pre-classified failure category for known phase-level failures such as artifact/proof validation errors. When present, recovery must honor this category directly instead of re-classifying the string reason heuristically.

Type:: FailureCategory | None

ralph.pipeline.events.pipeline_event¶

Pipeline event type enumeration.

class ralph.pipeline.events.pipeline_event.PipelineEvent(*values)[source]¶

Bases: StrEnum

Enumeration of all pipeline state-machine transition events.

ralph.pipeline.events.post_fanout_verification_event¶

Post-fanout verification event for the pipeline.

class ralph.pipeline.events.post_fanout_verification_event.PostFanoutVerificationEvent(success, exit_code=None, error=None)[source]¶

Bases: object

Event emitted after serialized workspace-wide verification runs post fan-out.

Parameters:

success (bool)
exit_code (int | None)
error (str | None)

success¶

Whether verification passed (exit code 0).

Type:: bool

exit_code¶

The verification subprocess exit code, or None if not run.

Type:: int | None

error¶

Human-readable error description when success=False, else None.

Type:: str | None

ralph.pipeline.events.worker_completed_event¶

Worker completed event for the pipeline.

class ralph.pipeline.events.worker_completed_event.WorkerCompletedEvent(unit_id, exit_code)[source]¶

Bases: object

Emitted when a parallel worker finishes successfully.

Parameters:

unit_id (str)
exit_code (int)

ralph.pipeline.events.worker_failed_event¶

Worker failed event for the pipeline.

class ralph.pipeline.events.worker_failed_event.WorkerFailedEvent(unit_id, exit_code, error)[source]¶

Bases: object

Emitted when a parallel worker terminates with a failure.

Parameters:

unit_id (str)
exit_code (int)
error (str)

ralph.pipeline.events.worker_started_event¶

Worker started event for the pipeline.

class ralph.pipeline.events.worker_started_event.WorkerStartedEvent(unit_id)[source]¶

Bases: object

Emitted when a parallel worker begins execution.

Parameters:: unit_id (str)

ralph.pipeline.handoffs¶

Pure helpers for phase handoff and drain resolution.

This module centralizes the policy-driven routing and phase-to-drain lookup used across the reducer and runtime. Keeping these helpers pure makes the handoff contract easy to unit test and keeps runtime injection limited to the policy data loaded at the composition root.

class ralph.pipeline.handoffs.ExhaustedAnalysisBypassResult(state, target_phase, skipped=())[source]¶

Bases: object

Resolved exhausted-analysis bypass outcome for a phase handoff.

Parameters:

state (PipelineState)
target_phase (PipelinePhase)
skipped (tuple[ExhaustedAnalysisSkip, ...])

class ralph.pipeline.handoffs.ExhaustedAnalysisSkip(phase, target_phase, iteration_field, iteration_value, max_iterations)[source]¶

Bases: object

Details for a single exhausted analysis phase that was bypassed.

Parameters:

phase (PipelinePhase)
target_phase (PipelinePhase)
iteration_field (str)
iteration_value (int)
max_iterations (int)

ralph.pipeline.handoffs.Handoff¶: alias of ExhaustedAnalysisBypassResult

ralph.pipeline.handoffs.resolve_exhausted_analysis_bypass(state, candidate_phase, pipeline_policy)[source]¶

Resolve exhausted-analysis re-entry from one canonical policy-driven helper.

The helper accepts an analysis phase candidate and follows that phase’s declared success transition whenever its loop budget is already exhausted. Each skipped analysis phase has its loop counter reset to 0 and its skip metadata recorded so reducer and runner paths can reuse the exact same bypass contract.

Parameters:

state (PipelineState)
candidate_phase (PipelinePhase)
pipeline_policy (PipelinePolicy)

Return type:

ralph.pipeline.handoffs.resolve_next_phase(current_phase, signal, pipeline_policy)[source]¶

Resolve the next phase based on a signal and the pipeline policy.

Parameters:

current_phase (PipelinePhase)
signal (str)
pipeline_policy (PipelinePolicy)

Return type:

ralph.pipeline.handoffs.resolve_phase_drain(phase, pipeline_policy)[source]¶

Return the configured drain for a phase.

Parameters:

phase (PipelinePhase)
pipeline_policy (PipelinePolicy)

Return type:

str | None

ralph.pipeline.handoffs.resolve_post_commit_phase(state, pipeline_policy)[source]¶

Resolve next phase for a successful commit with optional budget guards.

Routing is driven by post_commit_routes in policy, matched by phase name and budget_state. This works for any commit-role phase, not just the canonical development_commit/review_commit names.

Parameters:

state (PipelineState)
pipeline_policy (PipelinePolicy)

Return type:

ralph.pipeline.loopback¶

Shared loopback handlers for policy-driven phases.

ralph.pipeline.loopback.handle_capped_phase_loopback_policy_driven(state, policy, phase_def, *, review_outcome, advance_to_failed, resolve_or_terminal, advance_phase)[source]¶

Handle capped loopback using policy-declared loop_policy.

Parameters:

state (PipelineState)
policy (PipelinePolicy)
phase_def (PhaseDefinition)
review_outcome (str | None)
advance_to_failed (Callable[[PipelineState, str, PipelinePolicy | None], _EffectResult])
resolve_or_terminal (Callable[[PipelineState, str, PipelinePolicy, str], _EffectResult])
advance_phase (Callable[[PipelineState, str, PipelinePolicy | None], _EffectResult])

Return type:

_EffectResult

ralph.pipeline.phase_entry_cleaner¶

Phase-entry drain clearing for fresh phase entries.

This module handles the clearing of drain artifact files (JSON + Markdown handoff) when a pipeline phase is genuinely entered fresh — on program start, cross-phase transition, or last-commit re-entry — as opposed to same-phase retry or analysis loopback where the existing context should be preserved.

ralph.pipeline.phase_entry_cleaner.clear_phase_entry_drains(workspace, phase_name, previous_phase, pipeline_policy, artifacts_policy)[source]¶

Clear declared drain artifacts on genuine fresh phase entry.

Clears the primary JSON and Markdown handoff for each drain listed in the phase’s clear_drains_on_fresh_entry field, but only when is_fresh_phase_entry returns True.

Parameters:

workspace (Workspace) – The workspace to operate on.
phase_name (str) – The phase being entered.
previous_phase (str | None) – The previous phase from PreparePromptEffect.
pipeline_policy (PipelinePolicy) – The active pipeline policy.
artifacts_policy (ArtifactsPolicy) – The active artifacts policy.

Return type:

None

ralph.pipeline.phase_entry_cleaner.is_fresh_phase_entry(entering_phase, previous_phase, pipeline_policy)[source]¶

Return True when entering a phase via genuine fresh entry.

Fresh entry means program start, cross-phase transition, or last-commit re-entry. Clearing is suppressed for same-phase retry, analysis loopback, and checkpoint restore (resume). The resume case is handled by the caller via state-field check, not by this function.

Parameters:

entering_phase (str) – The phase being entered.
previous_phase (str | None) – The phase that preceded this entry (from PreparePromptEffect).
pipeline_policy (PipelinePolicy) – The active pipeline policy.

Returns:

True for genuine fresh entry; False for same-phase or analysis loopback.

Return type:

bool

ralph.pipeline.orchestrator¶

Pure orchestrator: determine next effect from state and policy.

This module implements the core routing logic that was previously hardcoded in the reducer’s match arms. Given the current PipelineState and the loaded PipelinePolicy + AgentsPolicy, determine_next_effect() returns the next Effect to execute.

No I/O, no side effects — fully deterministic and testable.

exception ralph.pipeline.orchestrator.PhaseHandlerNotFoundError(phase)[source]¶

Bases: Exception

Raised when no handler is registered for a phase.

Parameters:: phase (str)
Return type:: None

phase¶: Phase name that has no handler.

ralph.pipeline.orchestrator.determine_next_effect(state, pipeline_policy, agents_policy)[source]¶

Pure function: derive next effect from current state and policy.

This is the single routing function that replaces all hardcoded phase routing in the reducer. It consults the pipeline policy to determine which effect to emit based on: - The current phase definition (drain, transitions) - State flags (prompt prepared, agent invoked, analysis complete) - Budget counters (budget_caps / outer_progress, derived remaining)

Parameters:

state (PipelineState) – Current pipeline state.
pipeline_policy (PipelinePolicy) – Loaded pipeline policy (phase graph from pipeline.toml).
agents_policy (AgentsPolicy) – Loaded agents policy (chains and drain bindings).

Returns:

The next Effect to execute.

Return type:

Effect

ralph.pipeline.orchestrator.get_phase_drain(phase, pipeline_policy)[source]¶

Get the drain name for a given phase.

Parameters:

phase (PipelinePhase) – Phase name.
pipeline_policy (PipelinePolicy) – Loaded pipeline policy.

Returns:

Drain name or None if phase is not found.

Return type:

str | None

ralph.pipeline.orchestrator.resolve_next_phase(current_phase, signal, pipeline_policy)[source]¶

Backward-compatible wrapper for centralized handoff resolution.

Parameters:

current_phase (PipelinePhase)
signal (str)
pipeline_policy (PipelinePolicy)

Return type:

ralph.pipeline.orchestrator.resolve_post_commit_phase(state, pipeline_policy)[source]¶

Backward-compatible wrapper for centralized post-commit routing.

Parameters:

state (PipelineState)
pipeline_policy (PipelinePolicy)

Return type:

ParallelDisplay | LegacyConsoleDisplay

ralph.pipeline.parallel¶

Same-workspace parallel pipeline coordination.

This package provides the core components for running Ralph Workflow development phases in parallel across multiple worker processes within the same repository checkout (same-workspace fan-out, v1).

Supported public surface:

ParallelExecutionMode: Enumeration of supported parallel execution modes. Only SAME_WORKSPACE is supported in v1.
SameWorkspaceContext: Configuration for a same-workspace fan-out run, including repo root, per-worker namespace root, MCP factory, and optional executor command.
validate_for_same_workspace: Pre-flight validator that rejects overlapping, missing, or reserved edit areas before any worker is launched.

These are the only supported parallel primitives for v1. Per-worker branches and post-development branch reconciliation are explicitly out of scope for this iteration.

ralph.pipeline.parallel.coordinator¶

Structured concurrency coordinator for parallel development fan-out.

class ralph.pipeline.parallel.coordinator.ParallelCoordinator(*, activity_router=None)[source]¶

Bases: object

Orchestrates parallel work-unit execution with DAG dependency ordering.

Parameters:: activity_router (ActivityRouter | None)

async run_fan_out(effect, executor, display, ctx=None)[source]¶

Execute parallel work units while respecting DAG dependencies and worker caps.

Parameters:

effect (FanOutEffect)
executor (AgentExecutor)
display (ParallelDisplay)
ctx (WorkerContext | None)

Return type:

list[Event]

class ralph.pipeline.parallel.coordinator.WorkerContext(log=None, same_workspace=None, activity_router=None)[source]¶

Bases: object

Optional runtime context injected into each parallel worker.

Parameters:

log (WorkerLog | None)
same_workspace (SameWorkspaceContext | None)
activity_router (ActivityRouter | None)

exception ralph.pipeline.parallel.coordinator.WorkerFailureError(unit_id, exit_code, error)[source]¶

Bases: Exception

Raised internally when a parallel worker fails.

Parameters:

unit_id (str)
exit_code (int)
error (str)

Return type:

None

class ralph.pipeline.parallel.coordinator.WorkerLog(log_dir, run_id)[source]¶

Bases: object

Paths and identifiers for per-worker log files.

Parameters:

log_dir (Path)
run_id (str)

async ralph.pipeline.parallel.coordinator.run_fan_out(effect, executor, display, ctx=None, activity_router=None)[source]¶

Execute a fan-out effect using a fresh ParallelCoordinator instance.

Parameters:

effect (FanOutEffect)
executor (AgentExecutor)
display (ParallelDisplay)
ctx (WorkerContext | None)
activity_router (ActivityRouter | None)

Return type:

list[Event]

ralph.pipeline.parallel.mode¶

Parallel execution mode definitions for same-workspace parallel workers v1.

class ralph.pipeline.parallel.mode.ParallelExecutionMode(*values)[source]¶

Bases: StrEnum

Supported parallel execution modes.

In v1 only SAME_WORKSPACE is supported. Workers share the single checked-out repository root and are isolated only by edit-area path restrictions and per-worker artifact namespaces — not by filesystem isolation or separate git checkouts.

class ralph.pipeline.parallel.mode.SameWorkspaceContext(repo_root, mcp_factory, executor_command=None, worker_commands=<factory>, signal_bridge=None, worker_namespace_root=None, worker_manifest_paths=<factory>, session_drain='', session_capabilities=frozenset({}), session_model_identity=None, session_capability_profile=None)[source]¶

Bases: object

Runtime context for same-workspace parallel execution.

Workers run against repo_root directly. Per-worker mutable state lives under worker_namespace_root / <unit_id> / {artifacts,tmp,logs,handoffs}. Workers share one checkout; post-development coordination is state aggregation only.

The session contract fields (session_drain, session_capabilities, session_model_identity, session_capability_profile) carry the parent phase’s resolved MCP session plan verbatim so that parallel workers expose the same multimodal capability surface as the serial execution path.

Parameters:

repo_root (Path)
mcp_factory (McpServerFactory)
executor_command (tuple[str, ...] | None)
worker_commands (dict[str, tuple[str, ...]])
signal_bridge (SignalBridge | None)
worker_namespace_root (Path | None)
worker_manifest_paths (dict[str, Path])
session_drain (str)
session_capabilities (frozenset[str])
session_model_identity (MultimodalModelIdentity | None)
session_capability_profile (ResolvedCapabilityProfile | None)

ralph.pipeline.parallel.worker_manifest¶

Typed manifest model for a single parallel worker run.

class ralph.pipeline.parallel.worker_manifest.ParallelWorkerManifest(*, unit_id, description, allowed_directories, phase, drain, config_path=None, cli_overrides=<factory>, worker_namespace, worker_artifact_dir, prompt_file, workspace_root)[source]¶

Bases: BaseModel

Serializable manifest describing one isolated worker invocation.

Parameters:

unit_id (str)
description (str)
allowed_directories (list[str])
phase (str)
drain (str)
config_path (str | None)
cli_overrides (dict[str, object])
worker_namespace (str)
worker_artifact_dir (str)
prompt_file (str)
workspace_root (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_work_unit()[source]¶

Return the manifest payload as a WorkUnit for worker execution.

Return type:: WorkUnit

ralph.pipeline.parallel.worker_runtime¶

Early worker-runtime seam for dedicated parallel worker execution.

class ralph.pipeline.parallel.worker_runtime.WorkerRuntimePaths(checkpoint_path, current_prompt_path, prompt_dump_path, system_prompt_path, multimodal_sidecar_path)[source]¶

Bases: object

Worker-local filesystem paths for prompt and checkpoint runtime state.

Parameters:

checkpoint_path (Path)
current_prompt_path (Path)
prompt_dump_path (Path)
system_prompt_path (Path)
multimodal_sidecar_path (Path)

ralph.pipeline.parallel.worker_runtime.build_worker_runtime_paths(*, workspace_root, worker_namespace, phase)[source]¶

Return the namespaced runtime paths a parallel worker should own.

Parameters:

workspace_root (Path)
worker_namespace (Path)
phase (str)

Return type:

WorkerRuntimePaths

ralph.pipeline.parallel.worker_runtime.run_parallel_worker_from_manifest(*, manifest_path, display_context)[source]¶

Execute one manifest-backed worker flow without entering the shared run loop.

Parameters:

manifest_path (Path)
display_context (DisplayContext)

Return type:

int

ralph.pipeline.parallel.scheduler¶

Wave scheduler for parallel work-unit execution.

Provides schedule_next_wave, which selects the next batch of ready work units given the set of already-completed unit IDs, the full plan, currently running unit IDs, and the maximum worker concurrency. Units are ready when all their declared dependencies are in completed.

ralph.pipeline.parallel.scheduler.schedule_next_wave(completed, all_units, currently_running, max_workers)[source]¶

Return ready work units that can be launched in the next wave.

Parameters:

completed (set[str])
all_units (tuple[WorkUnit, ...])
currently_running (set[str])
max_workers (int)

Return type:

list[WorkUnit]

ralph.pipeline.parallel.worker_session¶

Factory helpers for building per-worker MCP session bundles.

Provides build_worker_session, which constructs an AgentSession, starts an MCP server for it via McpServerFactory, and returns a WorkerSessionBundle containing the session, its server handle, and the workspace scope that the worker should operate in.

class ralph.pipeline.parallel.worker_session.WorkerSessionBundle(session, mcp_handle, workspace_scope)[source]¶

Bases: object

Assembled session, MCP server handle, and workspace scope for a parallel worker.

Parameters:

session (AgentSession)
mcp_handle (McpServerHandle)
workspace_scope (WorkspaceScope)

class ralph.pipeline.parallel.worker_session.WorkerSessionConfig(worker_artifact_dir=None, worker_namespace=None, session_drain='', session_capabilities=frozenset({}), session_model_identity=None, session_capability_profile=None)[source]¶

Bases: object

Optional session contract parameters for a parallel worker session.

Parameters:

worker_artifact_dir (Path | None)
worker_namespace (Path | None)
session_drain (str)
session_capabilities (frozenset[str])
session_model_identity (MultimodalModelIdentity | None)
session_capability_profile (ResolvedCapabilityProfile | None)

ralph.pipeline.parallel.worker_session.build_worker_session(unit, mcp_factory, workspace_scope, config=None)[source]¶

Create an AgentSession, start an MCP server, and return the worker bundle.

Pass a WorkerSessionConfig to propagate session contract parameters (drain, capabilities, model identity, capability profile) from the parent phase’s SessionMcpPlan so the worker exposes the same multimodal capability surface as serial execution.

Parameters:

unit (WorkUnit)
mcp_factory (McpServerFactory)
workspace_scope (WorkspaceScope)
config (WorkerSessionConfig | None)

Return type:

WorkerSessionBundle

ralph.pipeline.parallel.parallel_execution_mode¶

Supported parallel execution modes.

class ralph.pipeline.parallel.parallel_execution_mode.ParallelExecutionMode(*values)[source]¶

Bases: StrEnum

Supported parallel execution modes.

ralph.pipeline.progress¶

Canonical workflow progress accounting.

This module owns all mutations for workflow progress fields, including completed outer progress counters, inner analysis-loop counters, routing budgets, review-issue flags tied to progress boundaries, and checkpoint-facing progress mirrors derived from canonical state and active policy.

Contract:

Outer progress counters are named by policy (via budget_counters); the runtime never assumes a specific counter name.
Analysis loopbacks mutate only the inner loop counter for the current cycle or pass.
Capped analysis loopback preserves outer progress and carries the inner loop counter to the cap until analysis or commit outcome resets it.
Skipped commits honour the commit_policy.skipped_advances_progress flag; when true (the default), a skip still advances outer progress and ends the current inner loop, so routing can distinguish a consumed-but-skipped iteration from one that never ran.
Checkpoint mirrors derive from canonical PipelineState and policy-declared budget counters: the first budget-tracked counter (in commit-phase BFS order) maps to actual_developer_runs; the second maps to actual_reviewer_runs.

ralph.pipeline.progress.advance_phase(state, target_phase, *, policy)[source]¶

Advance phases while applying only canonical routing-budget bookkeeping.

Parameters:

state (PipelineState)
target_phase (PipelinePhase)
policy (PipelinePolicy | None)

Return type:

PipelineState

ralph.pipeline.progress.apply_analysis_loopback(state, advanced_state, iteration_field, *, max_iterations, review_outcome=None)[source]¶

Apply canonical loopback bookkeeping for an analysis phase.

Parameters:

state (PipelineState)
advanced_state (PipelineState)
iteration_field (str)
max_iterations (int)
review_outcome (str | None)

Return type:

PipelineState

ralph.pipeline.progress.apply_analysis_success(state, advanced_state, *, policy=None)[source]¶

Reset inner-loop progress when analysis exits successfully to commit/approval.

Parameters:

state (PipelineState)
advanced_state (PipelineState)
policy (PipelinePolicy | None)

Return type:

PipelineState

ralph.pipeline.progress.apply_budget_counter_increment(state, advanced_state, counter)[source]¶

Increment a policy-declared budget counter when a lifecycle route completes.

Parameters:

state (PipelineState)
advanced_state (PipelineState)
counter (str | None)

Return type:

PipelineState

ralph.pipeline.progress.apply_commit_outcome(state, advanced_state, *, skipped, policy=None)[source]¶

Apply canonical outer-progress semantics for commit success vs skip.

Policy is required. Lifecycle-owned accounting takes precedence when the current phase is declared in pipeline.lifecycle_phases. Otherwise commit_policy drives the legacy fallback behavior.

Parameters:

state (PipelineState)
advanced_state (PipelineState)
skipped (bool)
policy (PipelinePolicy | None)

Return type:

PipelineState

ralph.pipeline.progress.derive_run_context_progress(state, run_context, policy=None)[source]¶

Derive checkpoint-facing progress mirrors from canonical pipeline state.

Resolves counter names by BFS through commit phases in the active policy; the first budget-tracked counter maps to actual_developer_runs, the second to actual_reviewer_runs. When policy is None, both fields are set to 0.

Parameters:

state (PipelineState)
run_context (RunContext)
policy (PipelinePolicy | None)

Return type:

RunContext

ralph.pipeline.progress.is_final_analysis_iteration(current_iteration, max_iterations)[source]¶

Return True when the current analysis state should be treated as final.

This intentionally matches the user-facing label semantics.

Parameters:

current_iteration (int)
max_iterations (int)

Return type:

bool

ralph.pipeline.progress.resolve_analysis_cap(state, iteration_field, policy)[source]¶

Resolve the effective analysis cap from canonical state/policy sources.

Parameters:

state (PipelineState)
iteration_field (str)
policy (PipelinePolicy)

Return type:

int

ralph.pipeline.progress.review_issues_found(state, policy=None)[source]¶

Return True when the current review outcome indicates issues were found.

When policy is provided, checks the active review phase’s clean_outcome to determine whether the stored review_outcome represents an issues-found state. When policy is None or no review phase with clean_outcome is declared, falls back to checking whether review_outcome is non-None.

Parameters:

state (PipelineState)
policy (PipelinePolicy | None)

Return type:

bool

ralph.pipeline.progress.should_skip_analysis_reentry(current_iteration, max_iterations)[source]¶

Return True when the next attempt to enter analysis must be skipped.

current_iteration stores completed loopbacks, while the visible FINAL label is rendered for the current run. That means re-entry should skip only after the final labeled run has already happened.

Parameters:

current_iteration (int)
max_iterations (int)

Return type:

bool

ralph.pipeline.reducer¶

Pure reducer: (state, event, policy) -> (new_state, effects).

No I/O, no side effects, fully deterministic.

This module implements the core state machine for the Ralph pipeline. Given the current state, an event, and the loaded policy, it computes the new state and any effects to execute.

The reducer is a PURE FUNCTION — it contains no I/O operations, no logging, and no mutable state. This makes it fully deterministic and easy to test.

Routing is driven by the policy: phase transitions come from pipeline.toml, not hardcoded match arms. All workflow semantics are expressed in policy.

ralph.pipeline.reducer.reduce(state, event, pipeline_policy=None, recovery=None)[source]¶

Pure state transition function.

This is the core of the Ralph pipeline state machine. Given the current state, an event, and the pipeline policy, it computes the new state and any effects to execute.

Parameters:

state (PipelineState) – Current pipeline state.
event (Event) – Event to process.
pipeline_policy (PipelinePolicy | None) – Pipeline policy for resolving transitions. Required for all routing decisions. Passing None causes routing handlers to route to the policy-declared failure route rather than silently falling back to hardcoded behavior.
recovery (RecoveryController | None) – Optional RecoveryController. When supplied, PhaseFailureEvents and worker failure events are delegated to it for classification-aware recovery (intelligent attribution, budget management). When None, the legacy retry/fallback logic is used.

Returns:

Tuple of (new_state, effects). Effects are instructions for the effect handler to execute.

Return type:

tuple[PipelineState, list[Effect]]

ralph.pipeline.runner¶

Pipeline runner: orchestration glue that wires extracted submodules together.

This module coordinates effect dispatch, step execution, and policy resolution. Heavy lifting is delegated to focused submodules; runner.py owns only the plumbing that connects them.

class ralph.pipeline.runner.AgentRegistry(*, ccs_defaults=None)[source]¶

Bases: object

Registry of available AI agents.

The registry maintains a mapping of agent names to their configurations. It supports loading agents from UnifiedConfig and resolving agent names at runtime.

Parameters:: ccs_defaults (CcsConfig | None)

agents¶: Dictionary mapping agent names to their configurations.

classmethod from_config(config)[source]¶

Create registry from UnifiedConfig.

Parameters:: config (UnifiedConfig) – Unified configuration containing agent definitions.
Returns:: Populated AgentRegistry instance.
Return type:: AgentRegistry

get(name)[source]¶

Get agent configuration by name.

Parameters:: name (str) – Agent name.
Returns:: AgentConfig if found, None otherwise.
Return type:: AgentConfig | None

get_command(name)[source]¶

Get the command for an agent.

Parameters:: name (str) – Agent name.
Returns:: Command string if agent found, None otherwise.
Return type:: str | None

list_agents()[source]¶

List all registered agent names.

Returns:: List of agent names.
Return type:: list[str]

register(name, config)[source]¶

Parameters:

name (str) – Agent name.
config (AgentConfig) – Agent configuration.

Return type:

None

validate()[source]¶

Validate all registered agents.

Returns:: List of validation error messages (empty if all valid).
Return type:: list[str]

class ralph.pipeline.runner.DynamicBindingMcpServerFactory(workspace, *, reserve_port=None, start_server=<function start_mcp_server>, lifecycle_deps=None)[source]¶

Bases: McpServerFactory

Build MCP server handles with dynamically allocated localhost endpoints.

Parameters:

workspace (WorkspaceLike)
reserve_port (Callable[[], int] | None)
start_server (StartServer)
lifecycle_deps (lifecycle.LifecycleDeps | None)

class ralph.pipeline.runner.McpSupervisor(bridge, *, check_interval=datetime.timedelta(seconds=2), on_restart=None, on_error=None)[source]¶

Bases: object

Background-thread supervisor for an active MCP server bridge.

Usage:

with McpSupervisor(bridge, on_restart=subscriber.record_mcp_restart):
    output = invoke_agent(...)
    stream_output(output)

The supervisor polls check_mcp_bridge_health(bridge) every check_interval seconds. Restarts are recorded via the optional on_restart callback. If the restart budget is exhausted, the stored McpServerError is re-raised when the context manager exits — taking priority over any agent-level error.

Parameters:

bridge (RestartAwareMcpBridge)
check_interval (timedelta)
on_restart (Callable[[int], None] | None)
on_error (Callable[[McpServerError], None] | None)

ralph.pipeline.runner.PendingPhaseTransitionMetadata¶: alias of _PendingPhaseTransitionMetadata

class ralph.pipeline.runner.SubprocessAgentExecutor(command, *, signal_bridge=None, cwd=None, extra_env=None, activity_router=None, raw_overflow_root=None, _pm=None)[source]¶

Bases: object

AgentExecutor that spawns a subprocess in its own process group.

Uses ProcessManager.spawn_async with start_new_session=True so the child gets its own process group, enabling escalating tree-kill on cancellation. Success or failure is determined by the coordinator from empirical evidence (artifact submission, git changes) — never from this executor’s exit code.

Parameters:

command (Sequence[str])
signal_bridge (SignalBridge | None)
cwd (Path | None)
extra_env (Mapping[str, str] | None)
activity_router (ActivityRouter | None)
raw_overflow_root (Path | None)
_pm (ProcessManager | None)

ralph.pipeline.runner.available_width(prefix_len)[source]¶

Return usable terminal width minus prefix and padding.

Parameters:: prefix_len (int)
Return type:: int

ralph.pipeline.runner.build_session_mcp_plan(*, transport, drain, workspace_path, agents_policy=None, model_opts=None, model_flag=None)[source]¶

Build the runtime MCP plan for a new agent session.

The result captures both session capability grants and any upstream MCP environment that must be present in the Ralph MCP subprocess so its runtime tool registry matches what the agent is expected to see.

Identity resolution precedence: 1. model_identity (explicit, if provided) 2. model_flag resolved via resolve_model_identity(transport, model_flag) 3. UNKNOWN_IDENTITY fallback

Parameters:

transport (AgentTransport | None)
drain (str)
workspace_path (Path | None)
agents_policy (AgentsPolicy | None)
model_opts (SessionModelOpts | None)
model_flag (str | None)

Return type:

SessionMcpPlan

ralph.pipeline.runner.check_mcp_bridge_health(bridge)[source]¶

Perform a health check on the MCP bridge, restarting if it crashed.

Only has an effect when bridge is a RestartAwareMcpBridge. Raises McpServerError when the restart budget is exhausted.

Parameters:: bridge (SessionBridgeLike)
Return type:: None

ralph.pipeline.runner.clear_cycle_baseline(workspace_root)[source]¶

Remove the baseline file so the next cycle starts fresh.

Parameters:: workspace_root (Path)
Return type:: None

ralph.pipeline.runner.commit_effect(workspace_root)[source]¶

Build a CommitEffect pointing at the standard commit message artifact path.

Parameters:: workspace_root (Path)
Return type:: CommitEffect

ralph.pipeline.runner.create_initial_state(config, *, agents_policy=None, pipeline_policy, counter_overrides=None)[source]¶

Create initial pipeline state from configuration.

Parameters:

config (UnifiedConfig)
agents_policy (AgentsPolicy | None)
pipeline_policy (PipelinePolicy)
counter_overrides (dict[str, int] | None)

Return type:

PipelineState

ralph.pipeline.runner.default_mcp_capabilities_for_phase(phase, *, agents_policy=None)[source]¶

Return the default MCP capability set for a given phase.

Parameters:

phase (str)
agents_policy (AgentsPolicy | None)

Return type:

set[str]

ralph.pipeline.runner.emit_final_summary(state, workspace_root, *, subscriber=None, display=None, display_context)[source]¶

Emit an end-of-run completion summary panel.

Parameters:

state (PipelineState)
workspace_root (Path)
subscriber (PipelineSubscriber | None)
display (ParallelDisplay | LegacyConsoleDisplay | None)
display_context (DisplayContext)

Return type:

None

ralph.pipeline.runner.emit_phase_transition_if_changed(display, previous_phase, state, *, verbosity, pipeline_policy)[source]¶

Emit phase-transition banners if the active phase changed, injecting patched banner hooks.

Parameters:

display (ParallelDisplay | LegacyConsoleDisplay)
previous_phase (str)
state (PipelineState)
verbosity (Verbosity)
pipeline_policy (PipelinePolicy)

Return type:

str

ralph.pipeline.runner.execute_agent_effect(effect, config, deps, workspace_scope, **opts)[source]¶

Execute an agent-invocation effect, injecting any patched MCP lifecycle hooks.

Parameters:

effect (InvokeAgentEffect)
config (UnifiedConfig)
deps (AgentExecutionDeps)
workspace_scope (WorkspaceScope)
opts (object)

Return type:

PipelineEvent

ralph.pipeline.runner.execute_commit_effect(effect, create_commit_fn, stage_all_fn, repo_root, display=None, **opts)[source]¶

Execute a commit effect, injecting any patched render_commit_message hook.

Parameters:

effect (CommitEffect)
create_commit_fn (Callable[[Path | str, str], str])
stage_all_fn (Callable[[Path | str], None])
repo_root (Path)
display (ParallelDisplay | LegacyConsoleDisplay | None)
opts (object)

Return type:

PipelineEvent

ralph.pipeline.runner.handle_phase(effect, ctx)[source]¶

Dispatch to the appropriate phase handler.

Parameters:

effect (InvokeAgentEffect | PreparePromptEffect | CommitEffect | EarlySkipCommitEffect | ExhaustedAnalysisPhaseAdvanceEffect | PushEffect | SaveCheckpointEffect | ExitSuccessEffect | ExitFailureEffect | FanOutEffect) – The effect that triggered this phase.
ctx (PhaseContext) – Phase context with workspace and policy.

Returns:

List of events to emit to the reducer.

Raises:

PhaseHandlerNotFoundError – If no handler is registered for the phase.

Return type:

ralph.pipeline.runner.heartbeat_policy_from_env(env=None)[source]¶

Return the configured MCP supervision check interval.

Parameters:: env (Mapping[str, str] | None)
Return type:: HeartbeatPolicy

ralph.pipeline.runner.install_signal_handlers(loop, root_task, bridge, controller=None)[source]¶

Parameters:

loop (asyncio.AbstractEventLoop)
root_task (asyncio.Task[object])
bridge (SignalBridge)
controller (InterruptController | None)

Return type:

None

ralph.pipeline.runner.install_width_refresher(ctx_holder, on_refresh=None)[source]¶

Install a width refresher using the best available strategy.

On POSIX main thread: uses SIGWINCH signal handler (install_sigwinch_refresher). On Windows or non-main thread: falls back to poll-based refresher (install_poll_refresher).

Parameters:

ctx_holder (list[DisplayContext]) – A single-element list whose 0th element is the DisplayContext to refresh on resize.
on_refresh (Callable[[DisplayContext], None] | None) – Optional callback invoked with the refreshed context after ctx_holder[0] is replaced.

Returns:

A stop() callable (for poll-based refresher; SIGWINCH handler has no cleanup).

Return type:

Callable[[], None]

ralph.pipeline.runner.make_display_context(*, env=None, console=None, force_width=None, force_mode=None, force_glyphs=None)[source]¶

Create a DisplayContext with resolved terminal metrics and adaptive limits.

Parameters:

env (Mapping[str, str] | None) – Environment mapping (defaults to os.environ).
console (Console | None) – Console to use (defaults to make_console() with env-aware color policy).
force_width (int | None) – Override terminal width detection.
force_mode (Literal['compact', 'medium', 'wide'] | None) – Override mode detection (‘compact’, ‘medium’, or ‘wide’).
force_glyphs (bool | None) – Override glyph detection (True=Unicode, False=ASCII, None=auto-detect).

Returns:

Fully initialised DisplayContext.

Return type:

DisplayContext

ralph.pipeline.runner.materialize_prompt_for_phase(context=None, options=None, **kwargs)[source]¶

Render and persist the prompt for a pipeline phase, returning its dump path.

Parameters:

context (PromptPhaseContext | None)
options (PromptPhaseOptions | None)
kwargs (object)

Return type:

str

ralph.pipeline.runner.materialize_system_prompt(*, workspace_root, name, default_current_prompt=None, worker_namespace=None)[source]¶

Write a system prompt file for the named agent and return its path.

Parameters:

workspace_root (Path)
name (str)
default_current_prompt (str | None)
worker_namespace (Path | None)

Return type:

str

ralph.pipeline.runner.phase_output_artifact_paths(phase, *, drain=None, policy_bundle=None)[source]¶

Return paths of all output artifacts produced by a phase.

Parameters:

phase (str)
drain (str | None)
policy_bundle (PolicyBundle | None)

Return type:

tuple[str, …]

ralph.pipeline.runner.prompt_session_drain_for_phase(drain, *, phase=None, pipeline_policy=None, agents_policy=None)¶

Return the prompt capability profile for a policy drain.

Parameters:

drain (str | None)
phase (str | None)
pipeline_policy (PipelinePolicy | None)
agents_policy (AgentsPolicy | None)

Return type:

SessionDrain

ralph.pipeline.runner.reducer_reduce(state, event, pipeline_policy=None, recovery=None)¶

Pure state transition function.

This is the core of the Ralph pipeline state machine. Given the current state, an event, and the pipeline policy, it computes the new state and any effects to execute.

Parameters:

state (PipelineState) – Current pipeline state.
event (Event) – Event to process.
pipeline_policy (PipelinePolicy | None) – Pipeline policy for resolving transitions. Required for all routing decisions. Passing None causes routing handlers to route to the policy-declared failure route rather than silently falling back to hardcoded behavior.
recovery (RecoveryController | None) – Optional RecoveryController. When supplied, PhaseFailureEvents and worker failure events are delegated to it for classification-aware recovery (intelligent attribution, budget management). When None, the legacy retry/fallback logic is used.

Returns:

Tuple of (new_state, effects). Effects are instructions for the effect handler to execute.

Return type:

tuple[PipelineState, list[Effect]]

ralph.pipeline.runner.register_role_handlers(policy)[source]¶

Called at policy-load time to ensure every phase with a recognized role has a handler registered, even if the phase name is not one of the canonical built-in names.

Execution-role phases are mapped to the generic handle_execution_phase.
Commit-role phases are mapped to the generic handle_commit_phase.
Analysis-role phases are mapped to the generic handle_generic_analysis_phase.
Review-role phases are mapped to the generic handle_review.
Verification-role phases are mapped to the generic handle_verification_phase.

Phases already registered via @register_handler are not overwritten.

Parameters:: policy (PipelinePolicy) – Loaded pipeline policy.
Return type:: None

ralph.pipeline.runner.render_commit_message(workspace_root, display_context)[source]¶

Render the commit message artifact as a titled block.

Parameters:

workspace_root (Path)
display_context (DisplayContext)

Return type:

None

ralph.pipeline.runner.resolve_display(display, display_context=None)[source]¶

Return the given display or construct a LegacyConsoleDisplay from display_context.

Parameters:

display (ParallelDisplay | None)
display_context (DisplayContext | None)

Return type:

ralph.pipeline.runner.resolve_workspace_scope(start=None)[source]¶

Resolve the active workspace scope.

The workspace root remains the active checkout, but linked worktrees inherit default .agent config from the main checkout unless the linked worktree has an explicit local override file.

Parameters:: start (Path | str | None)
Return type:: WorkspaceScope

ralph.pipeline.runner.run(config, initial_state=None, display=None, pipeline_subscriber=None, *, dashboard_subscriber=None, verbosity=None, connectivity_monitor=None, display_context=None, counter_overrides=None, config_path=None, cli_overrides=None, _recovery_sleep=None)[source]¶

Execute the pipeline event loop.

Parameters:

config (UnifiedConfig) – Unified configuration for the pipeline.
initial_state (PipelineState | None) – Optional initial state (for resume from checkpoint).
display (ParallelDisplay | None) – Optional pre-built display. When omitted, a ParallelDisplay is constructed by default unless verbosity is QUIET.
pipeline_subscriber (_PipelineSubscriberProtocol | None) – Optional subscriber that will receive notify(state) calls after each reduce.
verbosity (Verbosity | None) – Optional explicit verbosity. Defaults to the configured value in config.general.verbosity (mapped from int rank).
dashboard_subscriber (_PipelineSubscriberProtocol | None)
connectivity_monitor (_ConnectivityMonitorLike | None)
display_context (DisplayContext | None)
counter_overrides (dict[str, int] | None)
config_path (Path | None)
cli_overrides (dict[str, object] | None)
_recovery_sleep (Callable[[float], None] | None)

Returns:

Exit code (0 for success, non-zero for failure).

Return type:

int

async ralph.pipeline.runner.run_process_async(command, args=(), *, cwd=None, env=None, timeout=None, _pm=None)[source]¶

Run a process asynchronously and capture its output.

Parameters:

command (str)
args (Sequence[str])
cwd (str | Path | None)
env (Mapping[str, str] | None)
timeout (float | None)
_pm (ProcessManager | None)

Return type:

ProcessResult

ralph.pipeline.runner.show_phase_close_banner(exit_model, *, display_context, pipeline_policy=None)[source]¶

Display the close of a pipeline phase from a lifecycle exit model.

Canonical model-based path for phase-close rich banners. Symmetric with show_phase_start_from_entry(): same field ordering, same glyphs, same style keys. Appends elapsed time and exit trigger after the iteration context.

In medium and wide modes an additional stats line surfaces content/thinking/ tool/error counters from the exit model so the close banner is a full phase-level performance report.

Parameters:

exit_model (PhaseExitModel)
display_context (DisplayContext)
pipeline_policy (PipelinePolicy | None)

Return type:

None

ralph.pipeline.runner.show_phase_transition(from_phase, to_phase, *, context=None, display_context, pipeline_policy=None)[source]¶

Display a visual transition between pipeline phases.

Major transitions (e.g. planning → development) get a prominent banner. Minor transitions (e.g. development → development_analysis) get a simple rule.

When pipeline_policy is provided, styles and descriptions are derived from declared phase roles so renamed phases render correctly.

Parameters:

from_phase (str)
to_phase (str)
context (dict[str, object] | None)
display_context (DisplayContext)
pipeline_policy (PipelinePolicy | None)

Return type:

None

ralph.pipeline.runner.shutdown_mcp_server(bridge)[source]¶

Shutdown MCP server process.

Parameters:: bridge (SessionBridgeLike)
Return type:: None

ralph.pipeline.runner.start_mcp_server(session, workspace, *, upstream_registry=None, deps=None, extras=None)[source]¶

Start a standalone Ralph MCP HTTP subprocess and verify tool reachability.

Returns a RestartAwareMcpBridge that can auto-restart the server on crash up to the extras.restart_policy budget (default: 1000 restarts).

Parameters:

session (SessionLike)
workspace (WorkspaceLike)
upstream_registry (UpstreamRegistry | None)
deps (LifecycleDeps | None)
extras (McpServerExtras | None)

Return type:

RestartAwareMcpBridge

ralph.pipeline.activity_stream¶

Activity stream rendering and artifact handoff for the pipeline runner.

ralph.pipeline.activity_stream.render_phase_artifact_handoff(phase, event, workspace_root, display, ctx=None)[source]¶

Render the artifact handoff panel after a phase completes.

Parameters:

phase (str)
event (Event)
workspace_root (Path)
display (ParallelDisplay | LegacyConsoleDisplay | None)
ctx (ArtifactHandoffContext | None)

Return type:

None

ralph.pipeline.activity_stream.stream_parsed_agent_activity(lines, parser_type, agent_name, display=None, **kwargs)[source]¶

Stream and render parsed agent output lines.

Parameters:

lines (Iterable[object])
parser_type (str)
agent_name (str)
display (ParallelDisplay | LegacyConsoleDisplay | None)
kwargs (object)

Return type:

None

ralph.pipeline.effect_executor¶

Agent and commit effect execution for the pipeline runner.

ralph.pipeline.effect_executor.stage_files(repo_root, files)[source]¶

Stage only the provided repository-relative paths.

Uses git add --all -- <paths> so modified, untracked, and deleted files are all handled consistently for the selected scope.

Parameters:

repo_root (Path | str)
files (list[str])

Return type:

None

ralph.pipeline.effect_router¶

Effect routing: determine which effect to apply given the current pipeline state.

ralph.pipeline.effect_router.determine_effect_from_policy(state, policy_bundle, workspace_scope=None, *, config=None)[source]¶

Select the next pipeline effect based on current state and policy.

Parameters:

state (PipelineState)
policy_bundle (PolicyBundle)
workspace_scope (WorkspaceScope | None)
config (UnifiedConfig | None)

Return type:

Effect

ralph.pipeline.fan_out¶

Fan-out parallel execution for the pipeline runner.

ralph.pipeline.fan_out.execute_fan_out_sync(*, effect, state, display, **opts)[source]¶

Execute fan-out development synchronously by wrapping asyncio.run().

Parameters:

effect (FanOutEffect)
state (PipelineState)
display (ParallelDisplay | LegacyConsoleDisplay)
opts (object)

Return type:

PipelineState

ralph.pipeline.fan_out.write_parallel_development_summary(workspace_scope, effect, state, verification=None)[source]¶

Write .agent/artifacts/parallel_development_summary.json after fan-out completes.

Parameters:

workspace_scope (WorkspaceScope)
effect (FanOutEffect)
state (PipelineState)
verification (VerificationResult | None)

Return type:

None

ralph.pipeline.legacy_console_display¶

Legacy console display and display helper utilities for the pipeline runner.

class ralph.pipeline.legacy_console_display.LegacyConsoleDisplay(display_context)[source]¶

Bases: object

Legacy console display that uses a caller-provided DisplayContext.

Parameters:: display_context (DisplayContext)

ralph.pipeline.legacy_console_display.build_default_display(workspace_root, display_context, pipeline_policy=None)[source]¶

Construct the default ParallelDisplay for the verbose run path.

Falls back to the legacy console display if ParallelDisplay (or its transitive Rich/panel dependencies) cannot be imported or initialized.

Parameters:

workspace_root (Path)
display_context (DisplayContext)
pipeline_policy (PolicyBundle | None)

Return type:

ParallelDisplay | LegacyConsoleDisplay

ralph.pipeline.legacy_console_display.display_console(display, display_context=None)[source]¶

Return the underlying Rich Console for a display object.

Parameters:

display (ParallelDisplay | LegacyConsoleDisplay | None)
display_context (DisplayContext | None)

Return type:

Console

ralph.pipeline.legacy_console_display.emit_display_line(display, unit_id, line, display_context=None)[source]¶

Emit a line to the display, routing through the appropriate display type.

Parameters:

display (ParallelDisplay | LegacyConsoleDisplay | None)
unit_id (str | None)
line (Text | str)
display_context (DisplayContext | None)

Return type:

None

ralph.pipeline.legacy_console_display.get_display_context(display, display_context=None)[source]¶

Extract DisplayContext from display or use the caller-provided context.

Parameters:

display (ParallelDisplay | LegacyConsoleDisplay | None)
display_context (DisplayContext | None)

Return type:

DisplayContext

ralph.pipeline.legacy_console_display.resolve_display(display, display_context=None)[source]¶

Return the given display or construct a LegacyConsoleDisplay from display_context.

Parameters:

display (ParallelDisplay | None)
display_context (DisplayContext | None)

Return type:

ParallelDisplay | LegacyConsoleDisplay

ralph.pipeline.legacy_console_display.status_text(label, value, style)[source]¶

Create a styled status text line.

Parameters:

label (str)
value (str)
style (str)

Return type:

Text

ralph.pipeline.legacy_console_display.subscriber_for_display(display)[source]¶

Extract the pipeline subscriber from a display, when one is exposed.

Parameters:: display (ParallelDisplay | LegacyConsoleDisplay | None)
Return type:: PipelineSubscriber | None

ralph.pipeline.phase_agent_handler¶

Phase artifact rendering and post-agent-run event handling.

ralph.pipeline.phase_rendering¶

Verbosity ranking and normalization helpers for the pipeline runner.

ralph.pipeline.phase_rendering.normalize_verbosity(value)[source]¶

Coerce a Verbosity enum, integer rank, or None into a Verbosity value.

The legacy GeneralConfig.verbosity field is an integer (0-4); the new CLI surface is the Verbosity StrEnum. This helper accepts either and falls back to Verbosity.VERBOSE for unknown / unset inputs.

Parameters:: value (Verbosity | int | None)
Return type:: Verbosity

ralph.pipeline.phase_rendering.verbosity_rank(verbosity)[source]¶

Return a numeric rank for a Verbosity enum value (QUIET=0 .. DEBUG=4).

Parameters:: verbosity (Verbosity)
Return type:: int

ralph.pipeline.phase_transition¶

Phase transition display logic for the pipeline runner.

ralph.pipeline.phase_transition.PendingPhaseTransitionMetadata¶: alias of _PendingPhaseTransitionMetadata

ralph.pipeline.phase_transition.build_phase_entry_model_from_state(phase, state, pipeline_policy, *, agent_name=None)¶

Build the canonical phase-entry model from pipeline state.

Parameters:

phase (str)
state (PipelineState)
pipeline_policy (PipelinePolicy)
agent_name (str | None)

Return type:

PhaseEntryModel

ralph.pipeline.phase_transition.clear_phase_materialization_outputs(workspace, phase)¶

Remove stale prompt-materialization outputs for a phase when it is skipped.

Parameters:

workspace (FsWorkspace)
phase (str)

Return type:

None

ralph.pipeline.phase_transition.emit_final_summary(state, workspace_root, *, subscriber=None, display=None, display_context)[source]¶

Emit an end-of-run completion summary panel.

Parameters:

state (PipelineState)
workspace_root (Path)
subscriber (PipelineSubscriber | None)
display (ParallelDisplay | LegacyConsoleDisplay | None)
display_context (DisplayContext)

Return type:

None

ralph.pipeline.phase_transition.emit_phase_transition_if_changed(display, previous_phase, state, *, verbosity, pipeline_policy, show_close_banner_fn=None, show_transition_fn=None)¶

Emit the canonical close+transition display when the phase changes.

Returns the new previous_phase value (always state.phase). Quiet mode is a no-op except for state tracking.

Parameters:

display (ParallelDisplay | LegacyConsoleDisplay)
previous_phase (str)
state (PipelineState)
verbosity (Verbosity)
pipeline_policy (PipelinePolicy)
show_close_banner_fn (_ShowCloseBannerFn | None)
show_transition_fn (_ShowTransitionFn | None)

Return type:

str

ralph.pipeline.phase_transition.find_commit_counter_from_phase(phase_name, policy)¶

Trace on_success transitions to the nearest lifecycle or commit counter owner.

Returns the lifecycle-owned counter name when the phase graph declares one, otherwise falls back to the nearest commit phase increments_counter.

Parameters:

phase_name (str)
policy (PipelinePolicy)

Return type:

str | None

ralph.pipeline.phase_transition.show_phase_start_with_context(phase, agent_name, display_context, state, *, pipeline_policy)¶

Display the canonical model-based phase-start banner for the live runner.

Parameters:

phase (str)
agent_name (str)
display_context (DisplayContext)
state (PipelineState)
pipeline_policy (PipelinePolicy)

Return type:

None

ralph.pipeline.prompt_prep¶

Prompt materialization helpers for the pipeline runner.

ralph.pipeline.prompt_prep.prompt_session_drain_for_phase(drain, *, phase=None, pipeline_policy=None, agents_policy=None)¶

Return the prompt capability profile for a policy drain.

Parameters:

drain (str | None)
phase (str | None)
pipeline_policy (PipelinePolicy | None)
agents_policy (AgentsPolicy | None)

Return type:

SessionDrain

ralph.pipeline.prompt_prep.session_capabilities_for_agent_phase(drain, *, phase=None, pipeline_policy=None, agent=None, agents_policy=None)[source]¶

Return prompt session capabilities with the effective transport tool prefix.

Parameters:

drain (str | None)
phase (str | None)
pipeline_policy (PipelinePolicy | None)
agent (AgentConfig | None)
agents_policy (AgentsPolicy | None)

Return type:

SessionCapabilities

ralph.pipeline.run_loop¶

Pipeline event loop: the run() entry point and connectivity helpers.

ralph.pipeline.run_loop.run(config, initial_state=None, display=None, pipeline_subscriber=None, *, dashboard_subscriber=None, verbosity=None, connectivity_monitor=None, display_context=None, counter_overrides=None, config_path=None, cli_overrides=None, _recovery_sleep=None)[source]¶

Execute the pipeline event loop.

Parameters:

config (UnifiedConfig) – Unified configuration for the pipeline.
initial_state (PipelineState | None) – Optional initial state (for resume from checkpoint).
display (ParallelDisplay | None) – Optional pre-built display. When omitted, a ParallelDisplay is constructed by default unless verbosity is QUIET.
pipeline_subscriber (_PipelineSubscriberProtocol | None) – Optional subscriber that will receive notify(state) calls after each reduce.
verbosity (Verbosity | None) – Optional explicit verbosity. Defaults to the configured value in config.general.verbosity (mapped from int rank).
dashboard_subscriber (_PipelineSubscriberProtocol | None)
connectivity_monitor (_ConnectivityMonitorLike | None)
display_context (DisplayContext | None)
counter_overrides (dict[str, int] | None)
config_path (Path | None)
cli_overrides (dict[str, object] | None)
_recovery_sleep (Callable[[float], None] | None)

Returns:

Exit code (0 for success, non-zero for failure).

Return type:

int

ralph.pipeline.state_init¶

Initial pipeline state creation.

ralph.pipeline.state_init.create_initial_state(config, *, agents_policy=None, pipeline_policy, counter_overrides=None)[source]¶

Create initial pipeline state from configuration.

Parameters:

config (UnifiedConfig)
agents_policy (AgentsPolicy | None)
pipeline_policy (PipelinePolicy)
counter_overrides (dict[str, int] | None)

Return type:

PipelineState

ralph.pipeline.waiting_dispatch¶

Dispatch waiting status events to pipeline subscribers.

ralph.pipeline.waiting_dispatch.dispatch_waiting_event(event, *, subscriber, unit_id, agent_name)[source]¶

Dispatch a WaitingStatusEvent to the subscriber.

Exposed as a free function so tests can exercise it without a full pipeline.

Parameters:

event (object)
subscriber (PipelineSubscriber | None)
unit_id (str)
agent_name (str)

Return type:

None

ralph.pipeline.state¶

Immutable pipeline state model.

This module defines PipelineState - the single source of truth for pipeline execution progress. It serves dual purposes: 1. Runtime State: Tracks current phase, iteration counters, agent chain state 2. Checkpoint Payload: Serializes to JSON for resume functionality

PipelineState is IMMUTABLE from the reducer’s perspective. State transitions occur exclusively through the reduce function.

POLICY-DRIVEN STATE TRACKING¶

Loop counters (loop_iterations / loop_caps) and phase chains (phase_chains) are keyed by policy-declared names, not hardcoded field names. This enables custom workflows with arbitrary phase and counter names to work without modifying source code.

Budget counters (budget_caps / outer_progress) track the cap and completed cycles for each policy-declared budget counter. Remaining budget is always derived: remaining = max(0, cap - progress).

Legacy checkpoint fields (budget fields only) are migrated to the generic dicts at deserialise time via the _migrate_legacy_state_fields model_validator.

class ralph.pipeline.state.AgentChainState(*, agents=<factory>, current_index=0, retries=0)[source]

Bases: BaseModel

State for agent fallback chain management.

Parameters:

agents (list[str])
current_index (int)
retries (int)

agents

List of agent names in the fallback chain.

Type:: list[str]

current_index

Current agent index being used.

Type:: int

retries

Number of retries for current agent.

Type:: int

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_advance()[source]

Return a copy advanced to the next agent with retries reset to 0.

Return type:: AgentChainState

with_retry_increment()[source]

Return a copy with retries incremented by 1.

Return type:: AgentChainState

class ralph.pipeline.state.CommitState(*, message_prepared=False, diff_prepared=False, agent_invoked=False)[source]

Bases: BaseModel

State for commit operations.

Parameters:

message_prepared (bool)
diff_prepared (bool)
agent_invoked (bool)

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state.FalloverRecord(*, phase, from_agent, to_agent, timestamp_iso)[source]

Bases: BaseModel

A record of a single agent fallover event persisted in pipeline state.

Parameters:

phase (str)
from_agent (str)
to_agent (str)
timestamp_iso (str)

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state.PipelineState(*, phase='__unset__', previous_phase=None, review_outcome=None, phase_chains=<factory>, loop_iterations=<factory>, loop_caps=<factory>, budget_caps=<factory>, outer_progress=<factory>, rebase=<factory>, commit=<factory>, metrics=<factory>, checkpoint_saved_count=0, recovery_epoch=0, interrupted_by_user=False, git_auth_configured=False, pr_created=False, pr_url=None, push_count=0, last_error=None, last_reviewed_sha=None, policy_entry_phase='__unset__', policy_format_version=None, current_drain=None, work_units=<factory>, worker_states=<factory>, recovery_cycle_count=0, fallover_history=<factory>, last_failure_category=None, last_connectivity_state='unknown', recovery_cycle_cap=200, last_retry_delay_ms=0, last_agent_session_id=None, session_preserve_retry_pending=False)[source]

Bases: _FrozenPipelineStateModel

Immutable snapshot of pipeline execution state.

This is the checkpoint payload - the single source of truth for pipeline progress. Serialize it to JSON to save state; deserialize to resume interrupted runs.

GENERIC TRACKING FIELDS (policy-keyed):: phase_chains: Per-phase agent chain state keyed by canonical phase name. loop_iterations: Loop iteration counters keyed by iteration_state_field name. loop_caps: Loop iteration caps keyed by iteration_state_field name. budget_caps: Max budget keyed by budget counter name (seeded from policy). outer_progress: Completed cycle counts keyed by budget counter name. Remaining budget is derived on-demand: max(0, cap - progress).

Parameters:

phase (str)
previous_phase (str | None)
review_outcome (str | None)
phase_chains (dict[str, AgentChainState])
loop_iterations (dict[str, int])
loop_caps (dict[str, int])
budget_caps (dict[str, int])
outer_progress (dict[str, int])
rebase (RebaseState)
commit (CommitState)
metrics (RunMetrics)
checkpoint_saved_count (int)
recovery_epoch (int)
interrupted_by_user (bool)
git_auth_configured (bool)
pr_created (bool)
pr_url (str | None)
push_count (int)
last_error (str | None)
last_reviewed_sha (str | None)
policy_entry_phase (str)
policy_format_version (int | None)
current_drain (str | None)
work_units (tuple[WorkUnit, ...])
worker_states (dict[str, WorkerState])
recovery_cycle_count (int)
fallover_history (tuple[FalloverRecord, ...])
last_failure_category (str | None)
last_connectivity_state (str)
recovery_cycle_cap (Annotated[int, Ge(ge=1)])
last_retry_delay_ms (int)
last_agent_session_id (str | None)
session_preserve_retry_pending (bool)

advance_agent()[source]

Advance to the next agent in the fallback chain.

Return type:: PipelineState

chain_for_phase(phase)[source]

Get the tracked agent chain state for a phase, if any.

Parameters:: phase (str)
Return type:: AgentChainState | None

copy_with(**updates)[source]

Return a copy with updates applied in a typed-safe manner.

Parameters:: updates (object)
Return type:: PipelineState

current_agent()[source]

Get the current agent for the active phase.

Return type:: str | None

classmethod from_policy(policy, **overrides)[source]

Construct initial pipeline state from a loaded PipelinePolicy.

The entry phase is derived from policy.entry_phase so no workflow entry semantics are embedded in this class.

Parameters:

policy (PipelinePolicy)
overrides (object)

Return type:

PipelineState

get_budget_cap(counter_name)[source]

Get the budget cap for a policy-declared budget counter.

Parameters:: counter_name (str) – The budget counter name.
Returns:: Budget cap (maximum allowed), or 0 if not set.
Return type:: int

get_budget_remaining(counter_name)[source]

Get the remaining budget for a policy-declared budget counter.

Parameters:: counter_name (str) – The budget counter name from PhaseCommitPolicy.increments_counter.
Returns:: Remaining budget count, derived as max(0, cap - completed).
Return type:: int

get_loop_iteration(field_name)[source]

Get the loop iteration counter for a policy-declared iteration field.

Parameters:: field_name (str) – The iteration_state_field value from PhaseLoopPolicy.
Returns:: Current iteration count (0 when not yet set).
Return type:: int

get_outer_progress(counter_name)[source]

Get the completed cycle count for a policy-declared budget counter.

Parameters:: counter_name (str)
Return type:: int

is_complete(policy)[source]

Check if pipeline has reached a terminal success state.

Parameters:: policy (PipelinePolicy) – PipelinePolicy. Compares current phase against policy.terminal_phase to determine completion.
Raises:: RuntimeError – When policy is None (routing requires loaded policy).
Return type:: bool

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

remaining_retries()[source]

Calculate remaining retries for current agent.

Return type:: int

with_budget_cap(counter_name, value)[source]

Return a copy with the specified budget cap set to value.

Parameters:

counter_name (str)
value (int)

Return type:

PipelineState

with_drain(drain)[source]

Return a copy with the current_drain set.

Parameters:: drain (DrainName | None)
Return type:: PipelineState

with_fallover_record(record)[source]

Return a copy with one additional fallover record, trimmed to cycle cap.

Parameters:: record (FalloverRecord)
Return type:: PipelineState

with_loop_iteration(field_name, value)[source]

Return a copy with the specified loop iteration field set to value.

Parameters:

field_name (str) – The iteration_state_field value from PhaseLoopPolicy.
value (int) – New iteration count.

Returns:

New PipelineState with the iteration counter updated.

Return type:

PipelineState

with_outer_progress(counter_name, value)[source]

Return a copy with the specified outer progress counter set to value.

Parameters:

counter_name (str)
value (int)

Return type:

PipelineState

with_phase_chain(phase, chain)[source]

Return a copy with the chain state for the given phase updated.

Parameters:

phase (str)
chain (AgentChainState)

Return type:

PipelineState

class ralph.pipeline.state.RebaseState(*, pending=False, in_progress=False, completed=False)[source]

Bases: BaseModel

State for git rebase operations.

Parameters:

pending (bool)
in_progress (bool)
completed (bool)

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state.RunMetrics(*, total_agent_calls=0, total_continuations=0, total_fallbacks=0, total_retries=0)[source]

Bases: BaseModel

Run-level execution metrics.

Parameters:

total_agent_calls (int)
total_continuations (int)
total_fallbacks (int)
total_retries (int)

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_continuation_increment()[source]

Return a copy with total_continuations incremented by 1.

Return type:: RunMetrics

with_fallback_increment()[source]

Return a copy with total_fallbacks incremented by 1.

Return type:: RunMetrics

with_retry_increment()[source]

Return a copy with total_retries incremented by 1.

Return type:: RunMetrics

ralph.pipeline.work_units¶

Planning work_units parsing and validation.

This module provides a typed parser for work_units[] declared in planning artifacts. It intentionally focuses on schema and graph validation; execution fanout remains orchestrator-owned.

class ralph.pipeline.work_units.WorkUnit(*, unit_id, description, allowed_directories=<factory>, dependencies=<factory>)[source]¶

Bases: BaseModel

Single planning work unit declaration.

Parameters:

unit_id (Annotated[str, MinLen(min_length=1)])
description (Annotated[str, MinLen(min_length=1), MaxLen(max_length=4096)])
allowed_directories (list[str])
dependencies (list[str])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.work_units.WorkUnitsPlan(*, work_units=<factory>)[source]¶

Bases: BaseModel

Typed representation of work_units[] in planning artifacts.

Parameters:: work_units (list[WorkUnit])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception ralph.pipeline.work_units.WorkUnitsValidationError[source]¶

Bases: ValueError

Raised when a planning artifact contains invalid work_units.

ralph.pipeline.work_units.parse_work_units_from_artifact(artifact)[source]¶

Parse and validate work_units[] from a planning artifact payload.

Returns None when the artifact does not declare work_units.

Parameters:: artifact (Mapping[str, object])
Return type:: WorkUnitsPlan | None

ralph.pipeline.work_units.validate_for_same_workspace(plan)[source]¶

Validate that a plan is safe for same-workspace parallel execution.

Enforces rules that apply specifically when workers share the same checkout: - Every unit must declare at least one allowed_directory. - No unit may declare a reserved path (.agent, .git, .worktrees, ., “”). - No two units may have overlapping edit areas (prefix-overlap by path segments).

Raises:: WorkUnitsValidationError – with a human-readable message naming the problematic units/paths and suggesting a fix.
Parameters:: plan (WorkUnitsPlan)
Return type:: None

ralph.pipeline.worker_state¶

Worker execution state model for parallel pipeline workers.

class ralph.pipeline.worker_state.WorkerState(*, unit_id, status=WorkerStatus.PENDING, started_at=None, finished_at=None, exit_code=None, error_message=None, worker_namespace=None, log_file=None)[source]¶

Bases: BaseModel

Immutable snapshot of a single parallel worker’s execution state.

Parameters:

unit_id (Annotated[str, MinLen(min_length=1)])
status (WorkerStatus)
started_at (datetime | None)
finished_at (datetime | None)
exit_code (int | None)
error_message (str | None)
worker_namespace (str | None)
log_file (str | None)

unit_id¶

Identifier of the work unit this worker is executing.

Type:: str

status¶

Current execution status.

Type:: ralph.pipeline.worker_status.WorkerStatus

started_at¶

When the worker started execution.

Type:: datetime.datetime | None

finished_at¶

When the worker finished execution.

Type:: datetime.datetime | None

exit_code¶

Process exit code, if finished.

Type:: int | None

error_message¶

Human-readable error description, if failed.

Type:: str | None

worker_namespace¶

Filesystem path to the worker’s per-worker namespace under .agent/workers/<unit_id>/ in the shared checkout.

Type:: str | None

log_file¶

Path to the worker’s log file.

Type:: str | None

copy_with(**updates)[source]¶

Return a copy with the given fields replaced.

Parameters:: updates (object)
Return type:: WorkerState

model_config = {'extra': 'ignore', 'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.worker_state.WorkerStatus(*values)[source]¶

Bases: StrEnum

Execution status of a single parallel worker.

ralph.pipeline.exhausted_analysis_bypass_result¶

Exhausted-analysis bypass result model.

class ralph.pipeline.exhausted_analysis_bypass_result.ExhaustedAnalysisBypassResult(state, target_phase, skipped=())[source]¶

Bases: object

Resolved exhausted-analysis bypass outcome for a phase handoff.

Parameters:

state (PipelineState)
target_phase (PipelinePhase)
skipped (tuple[ExhaustedAnalysisSkip, ...])

ralph.pipeline.exhausted_analysis_skip¶

Exhausted-analysis skip details.

class ralph.pipeline.exhausted_analysis_skip.ExhaustedAnalysisSkip(phase, target_phase, iteration_field, iteration_value, max_iterations)[source]¶

Bases: object

Details for a single exhausted analysis phase that was bypassed.

Parameters:

phase (PipelinePhase)
target_phase (PipelinePhase)
iteration_field (str)
iteration_value (int)
max_iterations (int)

ralph.pipeline.frozen_work_unit_model¶

Shared frozen base model for work unit models.

class ralph.pipeline.frozen_work_unit_model.FrozenWorkUnitModel[source]¶

Bases: BaseModel

Shared base for frozen work unit models.

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.pipeline.state_models¶

Frozen sub-models used by the immutable pipeline state model.

class ralph.pipeline.state_models.AgentChainState(*, agents=<factory>, current_index=0, retries=0)[source]¶

Bases: BaseModel

State for agent fallback chain management.

Parameters:

agents (list[str])
current_index (int)
retries (int)

agents¶

List of agent names in the fallback chain.

Type:: list[str]

current_index¶

Current agent index being used.

Type:: int

retries¶

Number of retries for current agent.

Type:: int

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_advance()[source]¶

Return a copy advanced to the next agent with retries reset to 0.

Return type:: AgentChainState

with_retry_increment()[source]¶

Return a copy with retries incremented by 1.

Return type:: AgentChainState

class ralph.pipeline.state_models.CommitState(*, message_prepared=False, diff_prepared=False, agent_invoked=False)[source]¶

Bases: BaseModel

State for commit operations.

Parameters:

message_prepared (bool)
diff_prepared (bool)
agent_invoked (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state_models.FalloverRecord(*, phase, from_agent, to_agent, timestamp_iso)[source]¶

Bases: BaseModel

A record of a single agent fallover event persisted in pipeline state.

Parameters:

phase (str)
from_agent (str)
to_agent (str)
timestamp_iso (str)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state_models.RebaseState(*, pending=False, in_progress=False, completed=False)[source]¶

Bases: BaseModel

State for git rebase operations.

Parameters:

pending (bool)
in_progress (bool)
completed (bool)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.pipeline.state_models.RunMetrics(*, total_agent_calls=0, total_continuations=0, total_fallbacks=0, total_retries=0)[source]¶

Bases: BaseModel

Run-level execution metrics.

Parameters:

total_agent_calls (int)
total_continuations (int)
total_fallbacks (int)
total_retries (int)

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

with_continuation_increment()[source]¶

Return a copy with total_continuations incremented by 1.

Return type:: RunMetrics

with_fallback_increment()[source]¶

Return a copy with total_fallbacks incremented by 1.

Return type:: RunMetrics

with_retry_increment()[source]¶

Return a copy with total_retries incremented by 1.

Return type:: RunMetrics

ralph.pipeline.work_unit¶

Single planning work unit declaration.

class ralph.pipeline.work_unit.WorkUnit(*, unit_id, description, allowed_directories=<factory>, dependencies=<factory>)[source]¶

Bases: BaseModel

Single planning work unit declaration.

Parameters:

unit_id (Annotated[str, MinLen(min_length=1)])
description (Annotated[str, MinLen(min_length=1), MaxLen(max_length=4096)])
allowed_directories (list[str])
dependencies (list[str])

model_config = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.pipeline.work_units_validation_error¶

Validation error for work units planning artifacts.

exception ralph.pipeline.work_units_validation_error.WorkUnitsValidationError[source]¶

Bases: ValueError

Raised when a planning artifact contains invalid work_units.

ralph.pipeline.worker_status¶

Worker status enum for parallel execution.

class ralph.pipeline.worker_status.WorkerStatus(*values)[source]¶

Bases: StrEnum

Execution status of a single parallel worker.

Git¶

ralph.git.commit_cleanup¶

Git cleanup operations for commit hardening.

This module provides deterministic git operations for the commit cleanup phase, handling file deletion, gitignore updates, and git exclude patterns.

ralph.git.commit_cleanup.add_to_git_exclude(repo_root, patterns)[source]¶

Append patterns to .git/info/exclude for machine-local excludes.

Parameters:

repo_root (Path | str) – Path to the repository root.
patterns (list[str]) – List of patterns to add to exclude.

Return type:

None

ralph.git.commit_cleanup.delete_file_from_repo(repo_root, relative_path)[source]¶

Remove a file from the repository, unstaging if necessary.

Parameters:

repo_root (Path | str) – Path to the repository root.
relative_path (str) – Path relative to repo_root of the file to delete.

Return type:

None

ralph.git.commit_cleanup.ensure_git_initialized(repo_root)[source]¶

Ensure the directory is a git repository, initializing if necessary.

Parameters:: repo_root (Path | str) – Path to the repository root.
Return type:: None

Phases¶

ralph.phases¶

Phases module — phase handlers for the Ralph pipeline.

Each phase is implemented as a module that exports a handle_phase function. The handler receives an Effect and a PhaseContext, performs any necessary I/O (prompt preparation, agent invocation, artifact reading), and emits Events.

Phase handlers are registered by name in HANDLERS dict. Unknown phases in the pipeline graph will produce a PhaseHandlerNotFoundError at startup.

Two registration mechanisms are supported: 1. Decorator-based at import time: @register_handler(“phase_name”) 2. Role-based at policy-load time: register_role_handlers(policy)

The role-based mechanism registers the generic handler for every phase whose role matches a known role class (commit or analysis). This allows policy-renamed phases to work without hardcoded handler registration.

ralph.phases.analysis¶

Shared analysis logic for parsing analysis decisions.

The analysis phase reads a typed artifact submitted by the agent via MCP and extracts the decision field to route the pipeline.

Decision routing is driven entirely by policy: the phase’s decisions table in pipeline.toml maps raw status strings (from the agent artifact) to PhaseDecisionRoute targets. The reducer routes via decisions[status].target directly, so the raw status string is passed through as-is.

Decisions are raw strings from the agent artifact mapped to routes in policy. The BaseModel AnalysisDecision in ralph.mcp.artifacts.typed_artifacts is the artifact schema; routing uses the raw status string, not a StrEnum.

ralph.phases.analysis.handle_generic_analysis_phase(effect, ctx)[source]¶

Generic handler for analysis-role phases registered via register_role_handlers.

Used for policy-declared analysis phases whose names are not the canonical development_analysis or review_analysis. The handler:

Uses effect.phase as the pipeline policy phase name.
Uses effect.drain (if set) or effect.phase as the drain name for artifact path and vocabulary lookup.
Emits AnalysisDecisionEvent with the raw decision string, letting the reducer route directly through phase_def.decisions[status].target.

Parameters:

effect (Effect) – The effect that triggered this phase.
ctx (PhaseContext) – Phase context with workspace and policy.

Returns:

List of events to emit.

Return type:

list[Event]

ralph.phases.analysis.parse_analysis_decision_status(ctx, drain_name, *, phase_name=None)[source]¶

Parse the raw decision status string from the MCP artifact.

Reads the artifact file from the workspace and extracts the status field. The raw status string is returned directly — the reducer looks up the target in phase_def.decisions[status].target.

The drain_name is used to locate the artifact and vocabulary; the phase_name (defaults to drain_name when omitted) is used to look up the phase’s decisions table in pipeline policy.

Parameters:

ctx (PhaseContext) – Phase context with workspace and pipeline_policy.
drain_name (str) – Name of the drain (used for artifact path and vocabulary lookup).
phase_name (str | None) – Name of the phase in pipeline policy (defaults to drain_name).

Returns:

Raw status string, or None if parsing fails (caller should emit PhaseFailureEvent).

Return type:

str | None

ralph.phases.artifacts¶

Helpers for reading persisted MCP artifacts inside phase handlers.

exception ralph.phases.artifacts.PhaseArtifactError[source]¶

Bases: ValueError

Raised when a phase artifact is missing or malformed.

ralph.phases.artifacts.artifact_contract_for_drain(artifacts_policy, drain, artifact_type)[source]¶

Find the artifact contract for a drain/type pair if one exists.

Parameters:

artifacts_policy (object)
drain (str)
artifact_type (str)

Return type:

ArtifactContract | None

ralph.phases.artifacts.artifact_validation_failure_event(phase, reason, *, retry_in_session=True)[source]¶

Build a typed phase failure event for artifact/proof validation issues.

Parameters:

phase (str)
reason (str)
retry_in_session (bool)

Return type:

PhaseFailureEvent

ralph.phases.artifacts.decision_vocabulary_for_drain(artifacts_policy, drain, artifact_type)[source]¶

Return the allowed decision strings for a given drain and artifact type.

Parameters:

artifacts_policy (object)
drain (str)
artifact_type (str)

Return type:

list[str]

ralph.phases.artifacts.load_phase_artifact(workspace, path)[source]¶

Load a persisted MCP artifact wrapper from the workspace.

Parameters:

workspace (Workspace)
path (str)

Return type:

dict[str, object]

ralph.phases.artifacts.unwrap_phase_artifact_content(artifact, *, expected_type=None)[source]¶

Return the inner content payload from a persisted artifact wrapper.

Parameters:

artifact (Mapping[str, object])
expected_type (str | None)

Return type:

dict[str, object]

ralph.phases.commit¶

Commit phase handler.

Commit-role phases handle git operations after successful development or review phases. They stage and commit changes with an appropriate message.

If the working tree has no uncommitted changes when a commit phase is entered, the handler emits COMMIT_SKIPPED so the reducer can advance routing without incrementing iteration/reviewer_pass counters for a no-op pass.

The generic handle_commit_phase() function works for any phase with role=’commit’. It is registered exclusively via register_role_handlers(policy) at policy-load time for all commit-role phases declared in the active pipeline policy.

ralph.phases.commit.handle_commit_phase(effect, ctx)[source]¶

Generic commit phase handler for any role=’commit’ phase.

Stages and commits changes after a successful phase. When the working tree has no pending changes, emits COMMIT_SKIPPED so the pipeline advances without billing a progress counter for the no-op pass.

Parameters:

effect (Effect)
ctx (PhaseContext)

Return type:

list[Event]

ralph.phases.commit_cleanup¶

Commit cleanup phase handler.

This phase runs before the commit message phase to clean up any files that should not be committed (binaries, build artifacts, temporary files, etc.).

ralph.phases.commit_cleanup.handle_commit_cleanup_phase(effect, ctx)[source]¶

Handle the commit cleanup phase.

Behavior summary:

PreparePromptEffect returns PROMPT_PREPARED.
non-agent effects return [].
InvokeAgentEffect ensures git exists, validates the commit-cleanup artifact, applies cleanup actions, and returns AGENT_SUCCESS when analysis_complete=True or PHASE_LOOPBACK otherwise.
missing artifacts or failed cleanup actions return PhaseFailureEvent.

Parameters:

effect (Effect)
ctx (PhaseContext)

Return type:

list[Event]

ralph.phases.commit_logging¶

Commit logging session for tracking commit generation attempts.

Ported from ralph-workflow/src/phases/commit_logging/io.rs.

This module provides detailed logging for each commit generation attempt, creating a clear audit trail for debugging parsing failures.

class ralph.phases.commit_logging.CommitAttemptLog(attempt_number, agent, strategy, timestamp=<factory>, prompt_size_bytes=0, diff_size_bytes=0, diff_was_truncated=False, raw_output=None, outcome=None)[source]¶

Bases: object

Per-attempt log for commit message generation.

Parameters:

attempt_number (int)
agent (str)
strategy (str)
timestamp (datetime)
prompt_size_bytes (int)
diff_size_bytes (int)
diff_was_truncated (bool)
raw_output (str | None)
outcome (str | None)

class ralph.phases.commit_logging.CommitLoggingSession(run_dir, attempt_counter=0, is_noop=False)[source]¶

Bases: object

Session tracker for commit generation logging.

Parameters:

run_dir (Path)
attempt_counter (int)
is_noop (bool)

classmethod new(base_log_dir, workspace_exists_func, workspace_makedirs_func)[source]¶

Create a new logging session.

Creates a unique run directory under the base log path.

Parameters:

base_log_dir (str) – Base directory for logs.
workspace_exists_func (Callable[[Path], bool]) – Function to check if path exists (workspace.exists).
workspace_makedirs_func (Callable[[Path], None]) – Function to create directories (workspace.create_dir_all).

Returns:

A new CommitLoggingSession instance.

Return type:

CommitLoggingSession

new_attempt(agent, strategy)[source]¶

Create a new attempt log.

Parameters:

agent (str) – Agent name.
strategy (str) – Retry strategy.

Returns:

A new CommitAttemptLog instance.

Return type:

CommitAttemptLog

next_attempt_number()[source]¶

Get the next attempt number and increment the counter.

Returns:: The next attempt number.
Return type:: int

classmethod noop()[source]¶

Create a no-op logging session that discards all writes.

Returns:: A no-op CommitLoggingSession instance.
Return type:: CommitLoggingSession

write_attempt_log(attempt_log, workspace_write_func)[source]¶

Write an attempt log to a file.

Parameters:

attempt_log (CommitAttemptLog) – The attempt log to write.
workspace_write_func (Callable[[str, str], None]) – Function to write to workspace (workspace.write).

Return type:

None

write_summary(total_attempts, final_outcome, workspace_write_func)[source]¶

Write summary file at end of session.

For no-op sessions, this silently succeeds without writing anything.

Parameters:

total_attempts (int) – Total number of attempts.
final_outcome (str) – Final outcome string.
workspace_write_func (Callable[[str, str], None]) – Function to write to workspace (workspace.write).

Return type:

None

ralph.phases.execution¶

Generic execution phase handler.

Handles any phase with role=’execution’. Behavior is determined by the drain’s artifact contract:

Drain produces artifact_type=’plan’: plan validation, noop detection, plan draft management (PreparePromptEffect clears stale drafts).
Drain produces artifact_type=’development_result’: plan INPUT validation (noop short-circuit + work-unit policy check) before validating the output artifact.
All other drains: validate the configured output artifact contract only.

On PreparePromptEffect: clears a stale plan draft when the phase produces a plan. On InvokeAgentEffect: validates the output artifact contract, with type-specific pre-validation for plan and development_result drains.

ralph.phases.execution.handle_execution_phase(effect, ctx)[source]¶

Generic handler for any phase with role=’execution’.

Parameters:

effect (Effect) – The effect that triggered this phase.
ctx (PhaseContext) – Phase context with workspace and policy.

Returns:

List of events to emit.

Return type:

list[Event]

ralph.phases.integrity¶

PROMPT.md integrity helpers for Python phase execution.

class ralph.phases.integrity.IntegrityResult(ok, restored, prompt_path='PROMPT.md', backup_path=None, message='')[source]¶

Bases: object

Result of a PROMPT.md integrity verification pass.

Parameters:

ok (bool)
restored (bool)
prompt_path (str)
backup_path (str | None)
message (str)

ralph.phases.integrity.ensure_prompt_integrity(workspace, *, phase, iteration, prompt_path='PROMPT.md', backup_paths=('.agent/prompt.backup.md', '.agent/PROMPT.md.bak', '.agent/PROMPT.backup.md'))[source]¶

Ensure PROMPT.md is present, restoring from backup when possible.

Parameters:

workspace (Workspace)
phase (str)
iteration (int)
prompt_path (str)
backup_paths (tuple[str, ...])

Return type:

IntegrityResult

ralph.phases.integrity.find_prompt_backup(workspace, *, backup_paths=('.agent/prompt.backup.md', '.agent/PROMPT.md.bak', '.agent/PROMPT.backup.md'))[source]¶

Return the first available prompt backup path.

Parameters:

workspace (Workspace)
backup_paths (tuple[str, ...])

Return type:

str | None

ralph.phases.integrity.verify_prompt_integrity(workspace, *, prompt_path='PROMPT.md')[source]¶

Check that PROMPT.md exists and is non-empty.

Parameters:

workspace (Workspace)
prompt_path (str)

Return type:

IntegrityResult

ralph.phases.required_artifacts¶

Centralized required-artifact metadata for all pipeline phases.

Artifact metadata is split across two policy surfaces. artifacts.toml owns artifact type, JSON path, markdown handoff path, and schema normalizer lookup. pipeline.toml owns whether a phase’s output artifact is required for success. There are no built-in override tables — artifact paths must be declared in artifacts.toml and requiredness must be declared on the phase definition.

class ralph.phases.required_artifacts.RequiredArtifact(phase, artifact_type, json_path, markdown_path, normalizer, artifact_required=True)[source]¶

Bases: object

Metadata about an artifact contract for a pipeline phase.

When artifact_required is False, an absent artifact does not fail the phase; a present artifact is still validated.

Parameters:

phase (str)
artifact_type (str)
json_path (str)
markdown_path (str | None)
normalizer (Callable[[dict[str, object]], dict[str, object]] | None)
artifact_required (bool)

ralph.phases.required_artifacts.build_missing_input_hint(phase, upstream_phase, artifact_path)[source]¶

Build a retry hint for a phase that is missing a required upstream input artifact.

Unlike build_retry_hint (which describes a missing output), this function describes a missing input — i.e., a handoff that a prior phase should have produced. The hint is written to the phase’s retry-hint file so the agent sees an explanation on the next attempt, but the message correctly names the upstream producer rather than blaming the current agent.

Parameters:

phase (str)
upstream_phase (str)
artifact_path (str)

Return type:

str

ralph.phases.required_artifacts.build_proof_failure_hint(phase, detail)[source]¶

Build a retry hint for a phase that submitted proof but failed validation.

Parameters:

phase (str)
detail (str)

Return type:

str

ralph.phases.required_artifacts.build_required_artifacts(artifacts_policy)[source]¶

Build a drain-keyed artifact registry from ArtifactsPolicy.

The registry contains artifact identity and path metadata only. Callers that need phase-specific requiredness must use resolve_phase_required_artifact().

Parameters:: artifacts_policy (ArtifactsPolicy)
Return type:: dict[str, RequiredArtifact]

ralph.phases.required_artifacts.build_retry_hint(phase, detail, *, registry=None)[source]¶

Build a retry hint message for a phase that failed to submit a required artifact.

Parameters:

phase (str) – Pipeline phase name.
detail (str) – Error detail message.
registry (dict[str, RequiredArtifact] | None) – Optional policy-derived artifact registry. When provided, the hint includes the specific artifact type and path.

Return type:

str

ralph.phases.required_artifacts.resolve_phase_required_artifact(pipeline_policy, artifacts_policy, *, phase, drain=None)[source]¶

Resolve the artifact contract for a phase, including phase-owned requiredness.

Parameters:

pipeline_policy (PipelinePolicy)
artifacts_policy (ArtifactsPolicy)
phase (str)
drain (str | None)

Return type:

RequiredArtifact | None

ralph.phases.required_artifacts.resolve_required_artifact(artifacts_policy, *, drain)[source]¶

Resolve artifact identity/path metadata for a drain from artifacts.toml.

Parameters:

artifacts_policy (ArtifactsPolicy)
drain (str)

Return type:

RequiredArtifact | None

ralph.phases.required_artifacts.retry_hint_path(phase)[source]¶

Return the workspace-relative path for the retry hint file for a phase.

Parameters:: phase (str)
Return type:: str

ralph.phases.review¶

Generic review-role phase handler.

This handler may be registered for any phase declared with role=’review’. It does not assume the phase is named ‘review’: all emitted events derive the phase name from the incoming effect’s phase attribute.

When no new commits have landed since the last successful review pass, the handler emits REVIEW_CLEAN so the reducer routes straight to review_commit without invoking the reviewer agent. We intentionally treat any commit since the baseline as a trigger to re-review — even documentation churn — because the reviewer, not this handler, is the correct judge of which changes are substantive.

ralph.phases.review.handle_review(effect, ctx)[source]¶

Handle the review phase.

Parameters:

effect (Effect) – The effect that triggered this phase.
ctx (PhaseContext) – Phase context with workspace and policy.

Returns:

List of events to emit.

Return type:

list[Event]

ralph.phases.verification¶

Verification phase handler.

The verification phase enforces a policy-defined gating check before the pipeline can advance. The gate is declarative — it is validated at runtime against the configured verification kind.

Verification kinds: - artifact: the configured artifact path must exist and be non-empty - none: purely declarative gate; always passes

On gate failure, when on_failure_route is set, the handler emits PhaseFailureEvent(recoverable=False) so the reducer routes through _enter_failed_recovery to the policy-declared failure route. When on_failure_route is unset, the pipeline halts at the terminal failure route.

ralph.phases.verification.handle_verification_phase(effect, ctx)[source]¶

Generic handler for verification-role phases.

Dispatches on phase_def.verification.kind: - ‘artifact’: requires the configured artifact path to exist and be non-empty - ‘none’: purely declarative; emits AGENT_SUCCESS to advance

On gate failure, when on_failure_route is set, emits PhaseFailureEvent(recoverable=False) so the reducer routes to that target. When on_failure_route is unset, recoverable=False halts at the terminal failure.

Parameters:

effect (Effect) – The effect that triggered this phase.
ctx (PhaseContext) – Phase context with workspace and policy.

Returns:

List of events to emit.

Return type:

list[Event]

ralph.phases.timing¶

Phase timing utilities.

Provides monotonic-clock helpers and two dataclasses for measuring how long each pipeline phase takes:

PhaseTimer - start timing a phase with PhaseTimer.start(phase) and stop it with timer.finish() to get a PhaseTimingRecord.
PhaseTimingRecord - frozen record holding the phase name, iteration number, start timestamp, and elapsed timedelta / whole-second count.

All time values use time.monotonic so they are safe across system-clock adjustments. Elapsed seconds are truncated (not rounded) to whole integers.

class ralph.phases.timing.PhaseTimer(phase, iteration, started_at)[source]¶

Bases: object

Simple helper for measuring phase execution durations.

Parameters:

phase (str)
iteration (int)
started_at (float)

finish()[source]¶

Return a completed timing record for the phase.

Return type:: PhaseTimingRecord

classmethod start(phase, *, iteration=0)[source]¶

Start timing a phase.

Parameters:

phase (str)
iteration (int)

Return type:

PhaseTimer

class ralph.phases.timing.PhaseTimingRecord(phase, iteration, started_at, elapsed, elapsed_seconds)[source]¶

Bases: object

Structured timing result for a completed phase execution.

Parameters:

phase (str)
iteration (int)
started_at (float)
elapsed (timedelta)
elapsed_seconds (int)

ralph.phases.timing.capture_time()[source]¶

Return a monotonic timestamp suitable for elapsed-time calculations.

Return type:: float

ralph.phases.timing.elapsed(start)[source]¶

Return the duration since start using a monotonic clock.

Parameters:: start (float)
Return type:: timedelta

ralph.phases.timing.elapsed_seconds(start)[source]¶

Return whole elapsed seconds since start.

Parameters:: start (float)
Return type:: int

Agents¶

ralph.agents¶

Public agent-management exports.

This package exposes the small set of agent abstractions most callers need: registry lookup, chain composition, and process invocation.

Imports are resolved lazily so submodule imports like ralph.agents.clock do not pull in the full agent runtime during package initialization.

ralph.agents.activity¶

Watchdog-relevant activity signals emitted by agent transports.

class ralph.agents.activity.AgentActivityKind(*values)[source]¶

Bases: StrEnum

Kinds of agent activity that can reset the idle watchdog.

class ralph.agents.activity.AgentActivitySignal(kind, raw='')[source]¶

Bases: object

Small transport-neutral signal consumed by timeout control flow.

Parameters:

kind (AgentActivityKind)
raw (str)

ralph.agents.agent_activity_kind¶

Watchdog-relevant agent activity kind enumeration.

class ralph.agents.agent_activity_kind.AgentActivityKind(*values)[source]¶

Bases: StrEnum

Kinds of agent activity that can reset the idle watchdog.

ralph.agents.agent_chain¶

Agent fallback chain with retry and backoff behavior.

class ralph.agents.agent_chain.AgentChain(agents, max_retries=3, retry_delay_ms=1000, backoff_multiplier=2.0, max_backoff_ms=60000)[source]¶

Bases: object

Manages agent fallback chain with retry logic.

The chain maintains an ordered list of agents and handles: - Current agent selection - Retry counting and limits - Exponential backoff between retries - Fallback to next agent on exhaustion

Parameters:

agents (list[str])
max_retries (int)
retry_delay_ms (int)
backoff_multiplier (float)
max_backoff_ms (int)

agents¶: List of agent names in the chain.

current_index¶: Index of the currently selected agent.

retries¶: Number of retries for current agent.

max_retries¶: Maximum retries before falling back.

retry_delay_ms¶: Base delay between retries in milliseconds.

backoff_multiplier¶: Multiplier for exponential backoff.

max_backoff_ms¶: Maximum backoff delay in milliseconds.

advance()[source]¶

Advance to the next agent in the chain.

Returns:: True if advanced successfully, False if chain exhausted.
Return type:: bool

calculate_backoff()[source]¶

Calculate backoff delay in seconds.

Returns:: Backoff delay in seconds.
Return type:: float

can_retry()[source]¶

Check if current agent can be retried.

Returns:: True if retries remain for current agent.
Return type:: bool

property current_agent: str | None¶

Get the current agent name.

Returns:: Agent name or None if chain is exhausted.

property is_exhausted: bool¶

Check if all agents in chain are exhausted.

Returns:: True if no agents remain.

record_retry()[source]¶

Record a retry attempt for current agent.

Return type:: None

wait_backoff(*, _sleep=<built-in function sleep>)[source]¶

Wait for the backoff period.

Parameters:: _sleep (Callable[[float], None])
Return type:: None

ralph.agents.agent_entry¶

Minimal agent config protocol for availability checks.

class ralph.agents.agent_entry.AgentEntry(*args, **kwargs)[source]¶

Bases: Protocol

Minimal agent config interface for availability checks.

ralph.agents.clock¶

Clock protocol for the agent timeout subsystem.

class ralph.agents.clock.Clock(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for wall-clock operations used by the timeout subsystem.

monotonic()[source]¶

Return current monotonic time in seconds.

Return type:: float

sleep(seconds)[source]¶

Pause execution for the given number of seconds.

Parameters:: seconds (float)
Return type:: None

wait_for_event(event, seconds)[source]¶

Wait up to seconds for event to be set.

Returns True if the event was set during the wait, False on timeout. Production: uses event.wait() so line arrivals wake the poll loop immediately. Test: advances logical time by seconds and checks event state (no real wait).

Parameters:

event (threading.Event)
seconds (float)

Return type:

bool

ralph.agents.drain_not_bound_error¶

Errors raised when drain-to-chain binding is missing.

exception ralph.agents.drain_not_bound_error.DrainNotBoundError(drain, available_drains)[source]¶

Bases: Exception

Raised when a drain has no explicit chain binding.

Parameters:

drain (str)
available_drains (set[str])

Return type:

None

drain¶: The unbound drain name.

available_drains¶: Names of all bound drains.

ralph.agents.executor_error¶

Executor exception types.

exception ralph.agents.executor_error.ExecutorError[source]¶

Bases: Exception

Raised when an executor encounters an unrecoverable failure.

ralph.agents.system_clock¶

Production clock for the agent timeout subsystem.

class ralph.agents.system_clock.SystemClock(*args, **kwargs)[source]¶

Bases: Clock

Production Clock: uses real wall-clock time.

monotonic()[source]¶

Return current monotonic time in seconds.

Return type:: float

sleep(seconds)[source]¶

Pause execution for the given number of seconds.

Parameters:: seconds (float)
Return type:: None

wait_for_event(event, seconds)[source]¶

Wait up to seconds for event to be set.

Parameters:

event (Event)
seconds (float)

Return type:

bool

ralph.agents.unknown_agent_error¶

Errors raised when agent lookup fails.

exception ralph.agents.unknown_agent_error.UnknownAgentError(agent_name)[source]¶

Bases: Exception

Raised when an agent name is not found in the registry.

Parameters:: agent_name (str)
Return type:: None

agent_name¶: The unknown agent name.

ralph.agents.worker_result¶

Typed result returned by an agent executor.

class ralph.agents.worker_result.WorkerResult(unit_id, exit_code, final_message, duration_ms)[source]¶

Bases: object

Immutable result returned by an executor after a work unit finishes.

exit_code mirrors the subprocess exit status; 0 indicates success. final_message is the last status line emitted by the agent. duration_ms is the wall-clock elapsed time for the unit.

Parameters:

unit_id (str)
exit_code (int)
final_message (str)
duration_ms (int)

ralph.agents.availability¶

Agent PATH availability checks for Ralph Workflow.

Shared helper used by both the first-run welcome banner and the ralph –diagnose command to determine whether configured agents are reachable on the system PATH.

class ralph.agents.availability.AgentEntry(*args, **kwargs)[source]¶

Bases: Protocol

Minimal agent config interface for availability checks.

class ralph.agents.availability.HasListAgents(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for agent registries used in availability checks.

ralph.agents.availability.check_agent_availability(registry)[source]¶

Check which agents are available on PATH.

Parameters:: registry (HasListAgents) – Object implementing list_agents() and get(name) for agent resolution.
Returns:: List of (registry_name, status) tuples where status is one of ‘available’, ‘missing_on_path’, or ‘no_cmd’. The key is always the configured registry name so callers can join back to the registry without a secondary display-name lookup.
Return type:: list[tuple[str, Literal[‘available’, ‘missing_on_path’, ‘no_cmd’]]]

ralph.agents.chain¶

Agent fallback chain management with strict drain-to-chain binding.

This module handles the agent fallback chain — the ordered list of agents to try when an agent fails. It supports retry logic and exponential backoff.

IMPORTANT: This module implements STRICT drain-to-chain binding. Every drain must have an explicit binding in AgentsPolicy or startup validation fails. There is NO permissive fallback resolution — no sibling fallback, no inference, no default chains. If a drain is not bound, DrainNotBoundError is raised.

class ralph.agents.chain.AgentChain(agents, max_retries=3, retry_delay_ms=1000, backoff_multiplier=2.0, max_backoff_ms=60000)[source]¶

Bases: object

Manages agent fallback chain with retry logic.

The chain maintains an ordered list of agents and handles: - Current agent selection - Retry counting and limits - Exponential backoff between retries - Fallback to next agent on exhaustion

Parameters:

agents (list[str])
max_retries (int)
retry_delay_ms (int)
backoff_multiplier (float)
max_backoff_ms (int)

agents¶: List of agent names in the chain.

current_index¶: Index of the currently selected agent.

retries¶: Number of retries for current agent.

max_retries¶: Maximum retries before falling back.

retry_delay_ms¶: Base delay between retries in milliseconds.

backoff_multiplier¶: Multiplier for exponential backoff.

max_backoff_ms¶: Maximum backoff delay in milliseconds.

advance()[source]¶

Advance to the next agent in the chain.

Returns:: True if advanced successfully, False if chain exhausted.
Return type:: bool

calculate_backoff()[source]¶

Calculate backoff delay in seconds.

Returns:: Backoff delay in seconds.
Return type:: float

can_retry()[source]¶

Check if current agent can be retried.

Returns:: True if retries remain for current agent.
Return type:: bool

property current_agent: str | None¶

Get the current agent name.

Returns:: Agent name or None if chain is exhausted.

property is_exhausted: bool¶

Check if all agents in chain are exhausted.

Returns:: True if no agents remain.

record_retry()[source]¶

Record a retry attempt for current agent.

Return type:: None

wait_backoff(*, _sleep=<built-in function sleep>)[source]¶

Wait for the backoff period.

Parameters:: _sleep (Callable[[float], None])
Return type:: None

class ralph.agents.chain.ChainManager(agents_policy)[source]¶

Bases: object

Manages agent chains with strict drain-to-chain binding.

ChainManager is constructed with an AgentsPolicy and provides lookup of chains by drain name. Drain resolution is STRICT — there is no fallback or inference. If a drain is not explicitly bound, DrainNotBoundError is raised.

Parameters:: agents_policy (AgentsPolicy)

agents_policy¶: The agents policy containing chains and drain bindings.

chain_config_for_drain(drain)[source]¶

Alias for chain_for_drain for clarity.

Parameters:: drain (str)
Return type:: AgentChainConfig

chain_for_drain(drain)[source]¶

Get the chain configuration for a drain.

This is the STRICT drain resolution — no fallback, no inference. If the drain is not explicitly bound in agents.toml, DrainNotBoundError is raised at startup before any agent is invoked.

Parameters:: drain (str) – Drain name to look up.
Returns:: AgentChainConfig for the bound chain.
Raises:: DrainNotBoundError – If the drain is not explicitly bound.
Return type:: AgentChainConfig

classmethod from_config(config)[source]¶

Create ChainManager from a legacy UnifiedConfig.

This is a compatibility shim that converts the old UnifiedConfig format to the new AgentsPolicy format.

Parameters:: config (UnifiedConfig) – Legacy unified configuration.
Returns:: ChainManager instance.
Return type:: ChainManager

validate()[source]¶

Validate the policy for internal consistency.

Returns:: List of validation error messages (empty if valid).
Return type:: list[str]

exception ralph.agents.chain.DrainNotBoundError(drain, available_drains)[source]¶

Bases: Exception

Raised when a drain has no explicit chain binding.

Parameters:

drain (str)
available_drains (set[str])

Return type:

None

drain¶: The unbound drain name.

available_drains¶: Names of all bound drains.

exception ralph.agents.chain.UnknownAgentError(agent_name)[source]¶

Bases: Exception

Raised when an agent name is not found in the registry.

Parameters:: agent_name (str)
Return type:: None

agent_name¶: The unknown agent name.

ralph.agents.chain.create_chain_from_config(config, chain_name)[source]¶

Create an AgentChain from UnifiedConfig.

Parameters:

config (UnifiedConfig) – Unified configuration.
chain_name (str) – Name of the chain in agent_chains.

Returns:

AgentChain instance or None if chain not found.

Return type:

AgentChain | None

ralph.agents.completion_signals¶

Completion signal evaluation for OpenCode agent exits.

evaluate_completion() inspects the workspace artifacts directory and the raw NDJSON output to determine whether an OpenCode agent run produced the required phase artifact or explicitly declared completion via the declare_complete MCP tool. Explicit completion and artifact presence are separate signals; the explicit-complete flag is never auto-set just because a phase has no required artifact entry.

Phases whose pipeline definition marks the output artifact optional (artifact_required=False) are treated as terminal on a clean exit even when no artifact is produced and no explicit declare_complete call is made. The artifact provides context only; its absence does not gate phase success. A present optional artifact is still fully validated.

Phases without any artifact contract return required_artifact_present=False. OpenCode agents running such phases must still call declare_complete explicitly rather than relying on implicit success.

class ralph.agents.completion_signals.CompletionSignals(explicit_complete, required_artifact_present, artifact_types, terminal_ack_seen=False, artifact_optional=False)[source]¶

Bases: object

Signals that indicate whether an agent run actually completed its work.

Parameters:

explicit_complete (bool)
required_artifact_present (bool)
artifact_types (tuple[str, ...])
terminal_ack_seen (bool)
artifact_optional (bool)

explicit_complete¶

True when the agent called the declare_complete MCP tool successfully (independent of artifact presence).

Type:: bool

required_artifact_present¶

True when the required phase artifact exists on disk. False when the phase has no registered required artifact or the artifact file does not yet exist.

Type:: bool

artifact_types¶

Tuple of artifact type names found.

Type:: tuple[str, …]

terminal_ack_seen¶

True when a child_terminal lifecycle ACK was received from the OpenCode transport.

Type:: bool

artifact_optional¶

True when the phase marks its output artifact optional (artifact_required=False). A clean exit is terminal even without the artifact or an explicit declare_complete call.

Type:: bool

ralph.agents.completion_signals.evaluate_completion(workspace, raw_output=None, *, required_artifact=None)[source]¶

Check whether the agent run produced a required artifact or explicit completion.

explicit_complete is set from scanning raw_output for the declare_complete MCP tool marker, independently of artifact presence. required_artifact_present is True only when the artifact file exists on disk, parses as valid JSON, and contains a non-empty dict for phases that have a registered required artifact. Phases without a registered required artifact always return required_artifact_present=False so OpenCode agents cannot implicitly succeed — they must call declare_complete explicitly.

Parameters:

workspace (Path) – Workspace root path.
raw_output (list[str] | None) – Raw NDJSON lines from agent stdout for explicit-completion detection.
required_artifact (RequiredArtifact | None) – Policy-derived artifact metadata.

Returns:

CompletionSignals reflecting current artifact state and explicit completion.

Return type:

CompletionSignals

ralph.agents.completion_signals.extract_explicit_completion(raw_output)[source]¶

Return True if raw NDJSON output contains a successful declare_complete call.

Detects the unique marker produced by handle_declare_complete() in ralph/mcp/tools/coordination.py. The marker string only appears in the output when the agent successfully calls the declare_complete MCP tool.

Parameters:: raw_output (list[str]) – Raw NDJSON lines from the agent subprocess stdout.
Returns:: True if the declare_complete marker is found in any output line.
Return type:: bool

ralph.agents.execution_state¶

Transport-aware execution state model for agent lifecycle management.

Provides AgentExecutionState (active/waiting/resumable/terminal), the execution strategies, and OpenCode registry routing helpers.

ralph.agents.execution_state.agent_execution_state¶

Agent execution state enumeration.

class ralph.agents.execution_state.agent_execution_state.AgentExecutionState(*values)[source]¶

Bases: StrEnum

Execution state for an agent run.

ralph.agents.execution_state.claude_execution_strategy¶

Execution strategy for Claude agents.

class ralph.agents.execution_state.claude_execution_strategy.ClaudeExecutionStrategy[source]¶

Bases: GenericExecutionStrategy

Claude-aware activity classification for watchdog control flow.

classify_activity_line(line)[source]¶

Classify a raw output line for idle-watchdog activity.

Generic transports treat any non-blank line as activity while rejecting whitespace-only heartbeats so a process cannot evade the idle deadline without emitting meaningful provider output.

Parameters:: line (str)
Return type:: AgentActivitySignal | None

ralph.agents.execution_state.claude_interactive_execution_strategy¶

Execution strategy for interactive Claude agents.

class ralph.agents.execution_state.claude_interactive_execution_strategy.ClaudeInteractiveExecutionStrategy[source]¶

Bases: ClaudeExecutionStrategy

Interactive Claude session strategy.

Uses a VT-aware transcript parser before falling back to the headless Claude classifier so TUI repaint noise does not downgrade meaningful tool/lifecycle lines into generic output.

classify_activity_line(line)[source]¶

Classify a raw output line for idle-watchdog activity.

Generic transports treat any non-blank line as activity while rejecting whitespace-only heartbeats so a process cannot evade the idle deadline without emitting meaningful provider output.

Parameters:: line (str)
Return type:: AgentActivitySignal | None

ralph.agents.execution_state.generic_execution_strategy¶

Generic execution strategy for agents.

class ralph.agents.execution_state.generic_execution_strategy.GenericExecutionStrategy[source]¶

Bases: object

Default strategy: single-process lifetime, exit 0 is terminal success.

Replicates the behaviour that existed before the session-aware model was introduced so that Claude/Codex paths are unaffected.

classify_activity_line(line)[source]¶

Classify a raw output line for idle-watchdog activity.

Generic transports treat any non-blank line as activity while rejecting whitespace-only heartbeats so a process cannot evade the idle deadline without emitting meaningful provider output.

Parameters:: line (str)
Return type:: AgentActivitySignal | None

observe_line(line)[source]¶

Observe a raw provider line for optional strategy-specific state updates.

Parameters:: line (str)
Return type:: None

ralph.agents.execution_state.opencode_execution_strategy¶

Execution strategy for Opencode agents.

class ralph.agents.execution_state.opencode_execution_strategy.OpenCodeExecutionStrategy(*, label_scope=None, registry=None)[source]¶

Bases: object

OpenCode-aware strategy.

Idle classification checks the injectable LivenessProbe before falling back to the psutil-based has_live_descendants(), so unit tests can inject a FakeLivenessProbe without spawning real processes.

Exit classification uses evidence precedence:

terminal_ack_seen or schema-valid required artifact -> TERMINAL_COMPLETE
fresh progress in registry -> WAITING_ON_CHILD
live OS descendants with no fresh progress -> RESUMABLE_CONTINUE (stale)
else -> RESUMABLE_CONTINUE

label_scope narrows the Ralph-tracked liveness check to processes whose labels start with agent:{label_scope}:. When no scope is available, the empty-prefix registry-wide snapshot is consulted; the strategy never returns ACTIVE based on a never-matching sentinel.

Parameters:

label_scope (str | None)
registry (ChildLivenessRegistry | None)

classify_activity_line(line)[source]¶

Classify OpenCode output for idle-watchdog activity.

Parameters:: line (str)
Return type:: AgentActivitySignal | None

observe_line(line)[source]¶

Route a parsed output line into the child liveness registry.

Parameters:: line (str)
Return type:: None

ralph.agents.execution_state.agy_execution_strategy¶

Execution strategy for Google Anti Gravity (AGY) agents.

class ralph.agents.execution_state.agy_execution_strategy.AgyExecutionStrategy[source]¶

Bases: GenericExecutionStrategy

AGY strategy: completion evidence still required.

ralph.agents.executor¶

Agent executor protocol.

class ralph.agents.executor.AgentExecutor(*args, **kwargs)[source]¶

Bases: Protocol

Protocol that every agent executor implementation must satisfy.

Implementors receive a WorkUnit, stream output via on_output, report status transitions via on_status, and return a WorkerResult when the unit completes or fails.

exception ralph.agents.executor.ExecutorError[source]¶

Bases: Exception

Raised when an executor encounters an unrecoverable failure.

class ralph.agents.executor.WorkerResult(unit_id, exit_code, final_message, duration_ms)[source]¶

Bases: object

Immutable result returned by an executor after a work unit finishes.

exit_code mirrors the subprocess exit status; 0 indicates success. final_message is the last status line emitted by the agent. duration_ms is the wall-clock elapsed time for the unit.

Parameters:

unit_id (str)
exit_code (int)
final_message (str)
duration_ms (int)

ralph.agents.idle_watchdog¶

Idle watchdog for agent timeout policy enforcement.

IdleWatchdog owns the in-stream idle/deadline logic and exposes a single evaluate() method. All wall-clock decisions go through the injected Clock so the watchdog is fully testable without real sleeps (FakeClock) per CLAUDE.md test performance policy.

This module is the counterpart to ralph.agents.post_exit_watchdog.PostExitWatchdog, which owns post-exit (post-EOF) wall-clock timeouts. Together these two watchdogs cover every wall-clock timeout fire path in the agent invocation system; no ad-hoc clock.monotonic()/clock.sleep() loops are allowed in invoke.py.

IdleWatchdog owns fire reasons: SESSION_CEILING_EXCEEDED, NO_OUTPUT_DEADLINE, and CHILDREN_PERSIST_TOO_LONG. PostExitWatchdog owns: PROCESS_EXIT_HANG and DESCENDANT_HANG. See ralph.agents.post_exit_watchdog for the post-exit family.

ralph.agents.idle_watchdog.corroboration_snapshot¶

Corroboration snapshot for idle watchdog.

class ralph.agents.idle_watchdog.corroboration_snapshot.CorroborationSnapshot(workspace_event_count=None, oldest_child_seconds=None, scoped_child_active=None, scoped_child_count=None, terminal_child_events_total=None, last_activity_was_meaningful=None, alive_by=None)[source]¶

Bases: object

Advisory snapshot of corroborating signals for WAITING_ON_CHILD diagnosis.

All fields are Optional so callers without a given source can leave them None. Corroborators are advisory only; they NEVER affect WatchdogVerdict. The hard stop is determined solely by max_waiting_on_child_seconds and max_session_seconds.

Parameters:

workspace_event_count (int | None)
oldest_child_seconds (float | None)
scoped_child_active (bool | None)
scoped_child_count (int | None)
terminal_child_events_total (int | None)
last_activity_was_meaningful (bool | None)
alive_by (AliveBy | None)

ralph.agents.idle_watchdog.idle_watchdog¶

Idle watchdog for detecting stalled agents.

class ralph.agents.idle_watchdog.idle_watchdog.IdleWatchdog(config, clock, listener=None, *, corroborator=None)[source]¶

Bases: object

Tracks agent idle time and decides when to fire the timeout.

The watchdog owns the last_activity timestamp; the caller’s loop must NEVER mutate _last_activity directly. Activity must flow through record_activity(), which preserves the cumulative WAITING_ON_CHILD ceiling while advancing the idle baseline. Direct resets here previously caused a false-negative bug where WAITING_ON_CHILD deferred the deadline forever.

Cumulative WAITING_ON_CHILD time is an absolute ceiling that is preserved across every transition (heartbeat activity, drain windows, classify_quiet outcomes). Once recorded, cumulative time never decays during the session — this mirrors max_session_seconds semantics so neither ceiling can be defeated by a process that alternates between producing output and waiting on children.

The session ceiling (max_session_seconds) is checked first on every evaluate() call and cannot be defeated by activity — record_activity() does not reset it.

Status events are emitted via the optional listener: - ENTERED once when WAITING_ON_CHILD deferral begins. - PROGRESS at most once per waiting_status_interval_seconds (rate-limited). - SUSPECTED_FROZEN once per WAITING run when suspect threshold is crossed. - EXITED when transitioning out of WAITING_ON_CHILD. - HARD_STOP immediately before returning FIRE for CHILDREN_PERSIST_TOO_LONG.

Listener exceptions are caught and logged at DEBUG; they never propagate.

Parameters:

config (TimeoutPolicy)
clock (Clock)
listener (WaitingStatusListener | None)
corroborator (WaitingCorroborator | None)

property cumulative_waiting_on_child_seconds: float¶: Cumulative seconds spent in WAITING_ON_CHILD state across all runs.

evaluate(*, classify_quiet)[source]¶

Evaluate whether the watchdog should fire, wait, or continue.

The session ceiling is checked first (before idle deadline) because it is absolute and activity cannot reset it.

Parameters:: classify_quiet (Callable[[], AgentExecutionState]) – Called only when the idle deadline has elapsed; returns the current AgentExecutionState to distinguish child-wait from stall. Also called on every drain-window tick to detect newly appearing children (which abort the drain and resume deferral).
Returns:: keep running normally. WAITING_ON_CHILD: idle deadline elapsed; children still active; last_activity not reset. FIRE: idle deadline elapsed with no valid deferral; caller must terminate.
Return type:: CONTINUE

property last_fire_reason: WatchdogFireReason | None¶: The reason the watchdog fired, or None if it hasn’t fired yet.

record_activity()[source]¶

Record that the agent produced output; resets idle/drain/child state.

Does NOT reset _session_started_at — the session ceiling is absolute and cannot be defeated by heartbeat activity.

Does NOT reset _cumulative_waiting_on_child_seconds. Cumulative is a true absolute ceiling (parallel to the session ceiling) and never decays during the session.

Return type:: None

ralph.agents.idle_watchdog.timeout_policy¶

Timeout policy configuration for the idle watchdog.

class ralph.agents.idle_watchdog.timeout_policy.TimeoutPolicy(idle_timeout_seconds, drain_window_seconds=0.5, max_waiting_on_child_seconds=1800.0, max_session_seconds=None, idle_poll_interval_seconds=0.05, parent_exit_grace_seconds=5.0, descendant_wait_timeout_seconds=30.0, descendant_wait_poll_seconds=0.5, process_exit_wait_seconds=30.0, waiting_status_interval_seconds=30.0, suspect_waiting_on_child_seconds=600.0, max_waiting_on_child_no_progress_seconds=600.0)[source]¶

Bases: object

Consolidated timeout configuration for all agent timeout dimensions.

All timeout constants that previously appeared as module-level magic numbers in invoke.py are consolidated here so a single config-built TimeoutPolicy governs every timeout decision.

Precedence of fire conditions (in evaluation order):

SESSION_CEILING_EXCEEDED — absolute wall-clock cap; activity cannot reset it.
NO_OUTPUT_DEADLINE (+ drain window) — idle deadline since last output.
CHILDREN_PERSIST_TOO_LONG — cumulative WAITING_ON_CHILD ceiling; this is an absolute ceiling across the session and never decays.
PROCESS_EXIT_HANG — subprocess closed stdout but did not exit within budget.
DESCENDANT_HANG — descendant-wait deadline elapsed with persistent WAITING_ON_CHILD (post-exit only, owned by PostExitWatchdog).

Suspicion is purely informational and does NOT affect any fire condition. The suspect_waiting_on_child_seconds threshold exists only to emit an elevated warning event before the hard stop; crossing it never shortens the hard-stop ceiling.

Parameters:

idle_timeout_seconds (float | None)
drain_window_seconds (float)
max_waiting_on_child_seconds (float)
max_session_seconds (float | None)
idle_poll_interval_seconds (float)
parent_exit_grace_seconds (float)
descendant_wait_timeout_seconds (float)
descendant_wait_poll_seconds (float)
process_exit_wait_seconds (float)
waiting_status_interval_seconds (float)
suspect_waiting_on_child_seconds (float | None)
max_waiting_on_child_no_progress_seconds (float | None)

idle_timeout_seconds¶

Maximum seconds without output before watchdog may fire. None disables the idle-timeout watchdog entirely.

Type:: float | None

drain_window_seconds¶

After a potential timeout, the watchdog enters a drain window of this duration to allow late output to flush.

Type:: float

max_waiting_on_child_seconds¶

Hard cumulative ceiling on time spent in WAITING_ON_CHILD state across the entire session. Activity cannot decay or reset it; once exceeded, fires CHILDREN_PERSIST_TOO_LONG even while children are still alive.

Type:: float

max_session_seconds¶

Absolute wall-clock ceiling for the entire session. Activity cannot reset this ceiling. None means no ceiling (opt-in). When set, must be >= idle_timeout_seconds.

Type:: float | None

idle_poll_interval_seconds¶

How often the read loop polls for new lines. Values < 0.01s are intended for tests only.

Type:: float

parent_exit_grace_seconds¶

Grace window after parent rc=0 exit during which we poll for late completion signals or appearing children.

Type:: float

descendant_wait_timeout_seconds¶

Maximum time to wait for descendant processes to finish before declaring failure.

Type:: float

descendant_wait_poll_seconds¶

Poll interval for descendant-wait and process-exit-wait loops. Values < 0.01s are intended for tests only.

Type:: float

process_exit_wait_seconds¶

Maximum time to wait for a subprocess to exit after its stdout closes. Prevents hanging on subprocesses that close stdout but never call exit().

Type:: float

waiting_status_interval_seconds¶

How often to emit a PROGRESS status event while WAITING_ON_CHILD deferral is active. Controls only the status emission cadence; does NOT affect timeout safety or ceiling math.

Type:: float

suspect_waiting_on_child_seconds¶

Cumulative WAITING time after which a SUSPECTED_FROZEN event is emitted. Purely informational — does NOT shorten the hard-stop ceiling or change the watchdog verdict. Must be strictly less than max_waiting_on_child_seconds when set. None disables suspicion events.

Type:: float | None

max_waiting_on_child_no_progress_seconds¶

Hard ceiling on cumulative WAITING_ON_CHILD time when corroboration shows the child is alive but not making progress (e.g., heartbeat-only, stale-label, or OS-descendant-only evidence). When set, must be <= max_waiting_on_child_seconds. When None, the no-progress ceiling is disabled and max_waiting_on_child_seconds is used for all WAITING_ON_CHILD states.

Type:: float | None

ralph.agents.idle_watchdog.waiting_status_event¶

Waiting status event for idle watchdog corroboration.

class ralph.agents.idle_watchdog.waiting_status_event.WaitingStatusEvent(kind, cumulative_seconds, current_run_seconds, idle_elapsed_seconds, ceiling_seconds, suspect_threshold_seconds, diagnostic=<factory>)[source]¶

Bases: object

Structured status event emitted by IdleWatchdog during WAITING_ON_CHILD deferral.

This dataclass is frozen so subscribers cannot accidentally mutate shared state.

The diagnostic dict is a forward-compatible extension point for Phase 3 corroborating signals (workspace_event_delta, oldest_child_seconds, scoped_child_active, etc.). This plan ships only the throttle, transition, suspicion, and hard-stop summary semantics; Phase 3 fields are out of scope.

Parameters:

kind (WaitingStatusKind)
cumulative_seconds (float)
current_run_seconds (float)
idle_elapsed_seconds (float)
ceiling_seconds (float)
suspect_threshold_seconds (float | None)
diagnostic (dict[str, str | int | float | bool])

kind¶

The type of event (ENTERED, PROGRESS, SUSPECTED_FROZEN, EXITED, HARD_STOP).

Type:: WaitingStatusKind

cumulative_seconds¶

Cumulative WAITING_ON_CHILD seconds across the session so far.

Type:: float

current_run_seconds¶

Seconds spent in the current WAITING_ON_CHILD run.

Type:: float

idle_elapsed_seconds¶

Seconds since last record_activity() call.

Type:: float

ceiling_seconds¶

The active WAITING_ON_CHILD ceiling for this event.

Type:: float

suspect_threshold_seconds¶

The suspect_waiting_on_child_seconds threshold, or None.

Type:: float | None

diagnostic¶

Optional dict of extra diagnostic keys for HARD_STOP events.

Type:: dict[str, str | int | float | bool]

ralph.agents.idle_watchdog.waiting_status_kind¶

Enumeration of waiting status kinds for the idle watchdog.

class ralph.agents.idle_watchdog.waiting_status_kind.WaitingStatusKind(*values)[source]¶

Bases: StrEnum

Kind of waiting-status event emitted by IdleWatchdog.

ENTERED: transition into WAITING_ON_CHILD deferral. PROGRESS: periodic status update while still waiting (rate-limited). SUSPECTED_FROZEN: cumulative wait crossed suspect threshold; child may be frozen. EXITED: transition out of WAITING_ON_CHILD (activity or drain resumed). HARD_STOP: cumulative ceiling crossed; watchdog about to fire CHILDREN_PERSIST_TOO_LONG.

ralph.agents.idle_watchdog.watchdog_fire_reason¶

Enumeration of reasons the idle watchdog fires.

class ralph.agents.idle_watchdog.watchdog_fire_reason.WatchdogFireReason(*values)[source]¶

Bases: StrEnum

Why the watchdog decided to fire.

IdleWatchdog reasons (in-stream):: NO_OUTPUT_DEADLINE, CHILDREN_PERSIST_TOO_LONG, SESSION_CEILING_EXCEEDED.
PostExitWatchdog reasons (post-exit):: PROCESS_EXIT_HANG, DESCENDANT_HANG.

ralph.agents.idle_watchdog.watchdog_verdict¶

Enumeration of idle watchdog verdict outcomes.

class ralph.agents.idle_watchdog.watchdog_verdict.WatchdogVerdict(*values)[source]¶

Bases: StrEnum

Result of a watchdog evaluation cycle.

ralph.agents.post_exit_watchdog¶

Post-exit watchdog for agent subprocess and parent-exit timeout enforcement.

PostExitWatchdog owns all wall-clock timeout decisions that occur after the agent’s stdout stream has closed (EOF): the post-EOF process-exit hang window, the parent-exit grace window, and the descendant-quiesce window.

All wall-clock decisions go through the injected Clock so the watchdog is fully testable without real sleeps (FakeClock) per CLAUDE.md test performance policy.

This module is the counterpart to ralph.agents.idle_watchdog.IdleWatchdog, which owns in-stream idle/deadline timeouts. Every wall-clock timeout fire path in the agent invocation system routes through one of these two watchdogs; no ad-hoc clock.monotonic()/clock.sleep() loops are allowed in invoke.py.

Fire-reason precedence:

PROCESS_EXIT_HANG — PostExitWatchdog.wait_for_process_exit()
DESCENDANT_HANG — PostExitWatchdog.wait_descendant_quiesce()
(parent-exit grace does not fire; it returns verdicts that map to TERMINAL_COMPLETE / WAITING_ON_CHILD / RESUMABLE_CONTINUE)

class ralph.agents.post_exit_watchdog.PostExitVerdict(*values)[source]¶

Bases: StrEnum

Result of a PostExitWatchdog wait method.

class ralph.agents.post_exit_watchdog.PostExitWatchdog(policy, clock)[source]¶

Bases: object

Post-exit wall-clock watchdog for process-exit, parent-exit grace, and descendant-wait.

All three wait methods poll at policy.descendant_wait_poll_seconds intervals and delegate wall-clock reading to self._clock so tests can use FakeClock for deterministic, sub-second test runs.

Parameters:

policy (TimeoutPolicy)
clock (Clock)

last_verdict_reason¶

Set by wait_for_process_exit() when returning FIRE_PROCESS_EXIT_HANG; None otherwise. Exposed so integration tests can assert the correct reason without introspecting private state.

Type:: PostExitVerdict | None

wait_descendant_quiesce(classify_exit_state)[source]¶

Wait for descendant processes to quiesce within descendant_wait_timeout_seconds.

Polls classify_exit_state() at descendant_wait_poll_seconds intervals. If WAITING_ON_CHILD persists for the full deadline, FIRE_DESCENDANT_HANG is returned so the caller can fall back to RESUMABLE_CONTINUE semantics (raise OpenCodeResumableExitError) rather than treating this as silent success.

Parameters:: classify_exit_state (Callable[[], AgentExecutionState]) – Returns the current AgentExecutionState.
Returns:: TERMINAL_COMPLETE seen during polling. QUIESCED_NO_SIGNALS: RESUMABLE_CONTINUE seen (tree quiet before deadline). FIRE_DESCENDANT_HANG: deadline elapsed with WAITING_ON_CHILD persistent.
Return type:: SIGNALS_PRESENT

wait_for_process_exit(predicate_exit_observed)[source]¶

Wait for the subprocess to exit within process_exit_wait_seconds.

Checks the predicate BEFORE the first sleep so an already-exited process returns immediately without consuming any clock budget.

Parameters:: predicate_exit_observed (Callable[[], bool]) – Returns True when the subprocess has exited.
Returns:: subprocess exited (predicate returned True) before deadline. FIRE_PROCESS_EXIT_HANG: deadline elapsed with predicate still False.
Return type:: CONTINUE

wait_parent_exit_grace(classify_exit_state)[source]¶

Wait up to parent_exit_grace_seconds for completion signals or children.

Polls classify_exit_state() at descendant_wait_poll_seconds intervals. The grace window covers the race where MCP-driven background subagents have been launched but not yet registered with the ProcessManager.

Parameters:: classify_exit_state (Callable[[], AgentExecutionState]) – Returns the current AgentExecutionState by consulting evaluate_completion + execution_strategy.classify_exit.
Returns:: classify_exit_state returned TERMINAL_COMPLETE. CHILDREN_ACTIVE: classify_exit_state returned WAITING_ON_CHILD. QUIESCED_NO_SIGNALS: deadline elapsed with RESUMABLE_CONTINUE.
Return type:: SIGNALS_PRESENT

ralph.agents.invoke¶

Subprocess-based agent invocation with streaming NDJSON parsing.

This module handles invoking AI agents as subprocesses, parsing their streaming NDJSON output, and managing the lifecycle of the process.

Key features: - Line-by-line streaming from subprocess stdout to parser - tqdm progress bar (or rich when TTY) - loguru structured logging for every NDJSON line - watchdog workspace monitoring for file-change events during execution

exception ralph.agents.invoke.AgentInactivityTimeoutError(agent_name, timeout_seconds, parsed_output=None, opts=None)[source]¶

Bases: AgentInvocationError

Raised when an agent stalls without producing output.

Parameters:

agent_name (str)
timeout_seconds (float)
parsed_output (list[str] | None)
opts (InactivityTimeoutOpts | None)

Return type:

None

exception ralph.agents.invoke.AgentInvocationError(agent_name, returncode, stderr='', parsed_output=None)[source]¶

Bases: Exception

Raised when agent invocation fails.

Parameters:

agent_name (str)
returncode (int)
stderr (str)
parsed_output (list[str] | None)

Return type:

None

agent_name¶: Name of the agent that failed.

returncode¶: Process exit code.

stderr¶: Standard error output.

ralph.agents.invoke.BuildCommandOptions¶: alias of _BuildCommandOptions

ralph.agents.invoke.CompletionCheckOptions¶: alias of _CompletionCheckOptions

ralph.agents.invoke.IdleStreamTimeoutError¶: alias of _IdleStreamTimeoutError

class ralph.agents.invoke.InactivityTimeoutOpts(reason=None, session_resume_safe=False, diagnostic=None)[source]¶

Bases: object

Optional parameters for AgentInactivityTimeoutError.

Parameters:

reason (WatchdogFireReason | None)
session_resume_safe (bool)
diagnostic (dict[str, str | int | float | bool] | None)

exception ralph.agents.invoke.InteractivePermissionPromptError(agent_name, parsed_output)[source]¶

Bases: AgentInvocationError

Raised when interactive Claude reaches a permission prompt in unattended mode.

Parameters:

agent_name (str)
parsed_output (list[str])

Return type:

None

class ralph.agents.invoke.InvokeOptions(model_flag=None, session_id=None, verbose=False, show_progress=True, workspace_path=None, extra_env=None, idle_timeout_seconds=None, drain_window_seconds=None, max_waiting_on_child_seconds=None, idle_poll_interval_seconds=None, parent_exit_grace_seconds=None, descendant_wait_timeout_seconds=None, descendant_wait_poll_seconds=None, process_exit_wait_seconds=None, max_session_seconds=None, waiting_status_interval_seconds=None, suspect_waiting_on_child_seconds=None, child_progress_ttl_seconds=None, child_heartbeat_ttl_seconds=None, child_stale_label_ttl_seconds=None, child_exit_reconcile_seconds=None, max_waiting_on_child_no_progress_seconds=None, pure=False, system_prompt_file=None, waiting_listener=None, permission_prompt_listener=None, required_artifact=None, explicit_completion_seen=False, captured_session_id=None, initial_session_id=None, settings_json=None, stop_sentinel_path=None)[source]¶

Bases: object

Options for agent invocation.

Parameters:

model_flag (str | None)
session_id (str | None)
verbose (bool)
show_progress (bool)
workspace_path (Path | None)
extra_env (dict[str, str] | None)
idle_timeout_seconds (float | None)
drain_window_seconds (float | None)
max_waiting_on_child_seconds (float | None)
idle_poll_interval_seconds (float | None)
parent_exit_grace_seconds (float | None)
descendant_wait_timeout_seconds (float | None)
descendant_wait_poll_seconds (float | None)
process_exit_wait_seconds (float | None)
max_session_seconds (float | None)
waiting_status_interval_seconds (float | None)
suspect_waiting_on_child_seconds (float | None)
child_progress_ttl_seconds (float | None)
child_heartbeat_ttl_seconds (float | None)
child_stale_label_ttl_seconds (float | None)
child_exit_reconcile_seconds (float | None)
max_waiting_on_child_no_progress_seconds (float | None)
pure (bool)
system_prompt_file (str | None)
waiting_listener (WaitingStatusListener | None)
permission_prompt_listener (Callable[[str], None] | None)
required_artifact (RequiredArtifact | None)
explicit_completion_seen (bool)
captured_session_id (str | None)
initial_session_id (str | None)
settings_json (str | None)
stop_sentinel_path (Path | None)

class ralph.agents.invoke.InvokeRuntimeOptions(verbose=False, show_progress=True, workspace_path=None, extra_env=None, pure=False, session_id=None, system_prompt_file=None, waiting_listener=None, permission_prompt_listener=None, required_artifact=None)[source]¶

Bases: object

Non-timeout runtime options for agent invocation.

Parameters:

verbose (bool)
show_progress (bool)
workspace_path (Path | None)
extra_env (dict[str, str] | None)
pure (bool)
session_id (str | None)
system_prompt_file (str | None)
waiting_listener (WaitingStatusListener | None)
permission_prompt_listener (Callable[[str], None] | None)
required_artifact (RequiredArtifact | None)

exception ralph.agents.invoke.OpenCodeResumableExitError(agent_name, session_id=None)[source]¶

Bases: AgentInvocationError

Raised when an agent session exits without required completion evidence.

The session can be continued; the runner maps this into a session-preserving retry.

Parameters:

agent_name (str)
session_id (str | None)

Return type:

None

ralph.agents.invoke.ProcessReaderCtx¶: alias of _ProcessReaderCtx

class ralph.agents.invoke.ResolvedInvocationRuntime(agent_env=None, server_env=None, mcp_endpoint=None)[source]¶

Bases: object

Resolved runtime configuration for a single agent invocation.

Parameters:

agent_env (dict[str, str] | None)
server_env (dict[str, str] | None)
mcp_endpoint (str | None)

exception ralph.agents.invoke.UnsupportedMcpTransportError[source]¶

Bases: RuntimeError

Raised when MCP-backed execution is requested for an unsupported transport.

class ralph.agents.invoke.WatchdogFireReason(*values)[source]¶

Bases: StrEnum

Why the watchdog decided to fire.

IdleWatchdog reasons (in-stream):: NO_OUTPUT_DEADLINE, CHILDREN_PERSIST_TOO_LONG, SESSION_CEILING_EXCEEDED.
PostExitWatchdog reasons (post-exit):: PROCESS_EXIT_HANG, DESCENDANT_HANG.

class ralph.agents.invoke.WorkspaceMonitor(workspace_path)[source]¶

Bases: object

Monitors workspace directory for file changes during agent execution.

This allows the pipeline to detect when an agent has completed significant work by watching for file modifications in the workspace.

Parameters:: workspace_path (Path)

property changed_files: set[str]¶: Set of file paths that changed during monitoring.

property event_count: int¶: Number of file change events detected.

record_event(src_path)[source]¶

Record a file change event.

Parameters:: src_path (str) – Path to the changed file.
Return type:: None

start()[source]¶

Start monitoring the workspace for file changes.

Return type:: None

stop()[source]¶

Stop monitoring the workspace.

Return type:: None

ralph.agents.invoke.build_command(config, prompt_file, *, options=None)¶

Build the command line for agent invocation.

Parameters:

config (AgentConfig) – Agent configuration.
prompt_file (str) – Path to prompt file.
options (_BuildCommandOptions | None)

Returns:

List of command arguments.

Return type:

list[str]

ralph.agents.invoke.build_invoke_options_from_config(general_config, runtime=None)[source]¶

Build InvokeOptions from GeneralConfig, mapping all timeout fields.

Parameters:

general_config (GeneralConfig)
runtime (InvokeRuntimeOptions | None)

Return type:

InvokeOptions

ralph.agents.invoke.check_agent_available(config)[source]¶

Check if an agent command is available.

Parameters:: config (AgentConfig) – Agent configuration.
Returns:: True if agent command exists and is executable.
Return type:: bool

ralph.agents.invoke.check_process_result(handle, agent_name, parsed_output=None, check_options=None, *, _clock=None)¶

Check subprocess return code and raise error if non-zero.

For session-continuing agents, exit 0 without required completion evidence raises OpenCodeResumableExitError so the runner can continue the same session. When the process exits but child agents are still running, this function waits up to policy.descendant_wait_timeout_seconds for the tree to quiesce before re-evaluating completion signals.

Parameters:

handle (ManagedProcess | ManagedPtyProcess) – Completed managed process.
agent_name (str) – Name of the agent.
_clock (Clock | None) – Injectable Clock for testing; production callers omit this.
parsed_output (list[str] | None)
check_options (_CompletionCheckOptions | None)

Raises:

AgentInvocationError – If process exited with non-zero code.
OpenCodeResumableExitError – If the agent session exited without required completion evidence and no child agents are still running.

Return type:

None

ralph.agents.invoke.extract_session_id(raw_output)[source]¶

Extract a nested session identifier from raw NDJSON output lines.

Parameters:: raw_output (list[str] | tuple[str, ...])
Return type:: str | None

ralph.agents.invoke.get_process_manager(*, policy=None)[source]¶

Return the module-level ProcessManager singleton, creating it on first call.

Parameters:: policy (ProcessManagerPolicy | None)
Return type:: ProcessManager

ralph.agents.invoke.invoke_agent(config, prompt_file, *, options=None, _clock=None)[source]¶

Invoke agent, yield parsed output lines as they arrive.

Parameters:

config (AgentConfig) – Agent configuration specifying command and flags.
prompt_file (str) – Path to PROMPT.md file to pass to agent.
options (InvokeOptions | None) – Optional invocation options.
_clock (Clock | None) – Injectable Clock for testing; production callers omit this.

Yields:

Raw agent output lines (before parsing).

Raises:

AgentInvocationError – If agent exits with non-zero code.

Return type:

Iterator[str]

ralph.agents.invoke.policy_from_options(opts)¶

Build a TimeoutPolicy from InvokeOptions, falling back to policy defaults for None fields.

Parameters:: opts (InvokeOptions)
Return type:: TimeoutPolicy

ralph.agents.invoke.resolve_invocation_runtime(config, extra_env, workspace_path, *, _base_env=None, system_prompt_file=None)[source]¶

Build the runtime configuration needed to launch an agent.

Resolves transport-specific environment variables, MCP server configuration, and endpoint address from config and extra_env. Returns a ResolvedInvocationRuntime whose fields are ready to pass to the subprocess launcher.

Parameters:

config (AgentConfig)
extra_env (dict[str, str] | None)
workspace_path (Path | None)
_base_env (Mapping[str, str] | None)
system_prompt_file (str | None)

Return type:

ResolvedInvocationRuntime

ralph.agents.invoke.run_subprocess_and_read_lines(cmd, ctx)¶

Run subprocess and yield output lines.

Parameters:

cmd (list[str]) – Command to execute.
ctx (_AgentRunCtx) – Agent run context with configuration and options.

Yields:

Output lines from the subprocess.

Return type:

Iterator[str]

ralph.agents.invoke.wait_for_descendants_then_recheck(handle, opts, parsed_output, *, clock=None)¶

Wait for descendant processes to finish, then re-evaluate completion signals.

Polls the execution strategy’s classify_exit at policy.descendant_wait_poll_seconds intervals until either the tree is quiet (state != WAITING_ON_CHILD) or the deadline elapses. This allows artifacts written by background subagents to become visible before OpenCodeResumableExitError is raised.

Parameters:

handle (ManagedProcess | ManagedPtyProcess) – Completed parent process handle.
opts (_CompletionCheckOptions) – Completion check options including liveness_probe and policy.
parsed_output (list[str]) – Raw NDJSON output lines from the agent.
clock (Clock | None) – Injectable Clock; defaults to SystemClock.

Returns:

TERMINAL_COMPLETE if tree quiessed and completion signals present. RESUMABLE_CONTINUE if deadline elapsed with children still alive (fallback to retry rather than silent success). WAITING_ON_CHILD is only returned during the active polling loop, never after deadline.

Return type:

AgentExecutionState

ralph.agents.parsers¶

Agent output parsers: one per agent transport, plus a generic fallback.

This package converts raw stdout lines from an agent subprocess into structured AgentOutputLine objects for the invocation engine in ralph.agents.invoke.

Main entry points:

get_parser(parser_type) — factory function; maps a parser type name string ('claude', 'codex', 'gemini', 'opencode', 'generic') to the corresponding parser instance. Raises ValueError for unknown names.
AgentParser — the protocol that all parsers implement; defines parse_line.
AgentOutputLine — structured parse result (content, kind, raw text).
ClaudeParser — parses Claude stream-JSON NDJSON output.
CodexParser — parses Codex per-event JSON output.
GeminiParser — parses Gemini output.
OpenCodeParser — parses OpenCode NDJSON stream output.
GenericParser — fallback parser for unknown or plain-text agent output.

Parser selection is driven by AgentConfig.json_parser (a JsonParserType enum value in ralph.config.enums). The invocation engine calls get_parser() at the start of each agent run and feeds every stdout line through parser.parse_line().

To add a parser for a new agent transport, create a module in this package, implement AgentParser, and register the class in both get_parser() and __all__.

ralph.agents.parsers.base¶

Base types for agent output parsing.

This module defines the parser protocol and shared text-block helpers.

class ralph.agents.parsers.base.AgentParser(*args, **kwargs)[source]¶

Bases: Protocol

Protocol all parser modules must implement.

A parser takes raw lines from an agent’s stdout and yields normalized AgentOutputLine instances.

parse(lines)[source]¶

Parse agent output lines.

Parameters:: lines (Iterator[str]) – Iterator of raw lines from agent stdout.
Yields:: Normalized AgentOutputLine instances.
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.base.stringify_text_blocks(value, *, require_text_type=False)[source]¶

Extract text from a string or a list of text-block dicts.

Parameters:

value (object) – A plain string, or a list of dicts with a ‘text’ field.
require_text_type (bool) – When True, only include dicts where type==’text’ (Claude tool_result rule). When False, include any dict with a ‘text’ key (OpenCode output rule). In both modes, multimodal blocks (image, resource_reference) emit a bounded readable placeholder rather than being silently dropped.

Return type:

str

ralph.agents.parsers.claude¶

Parser for Claude’s NDJSON streaming format.

class ralph.agents.parsers.claude.ClaudeParser[source]¶

Bases: object

Parser for Claude’s NDJSON streaming output with robust delta accumulation.

Text deltas are accumulated into coherent blocks before emission, flushing on: - content_block_stop (end of a content block) - message_stop (end of the message) - \n\n paragraph boundary (incremental surfacing of long responses)

Thinking deltas (thinking_delta) are accumulated separately from text deltas and emitted as type="thinking" lines.

parse(lines)[source]¶

Parse Claude streaming NDJSON lines.

Parameters:: lines (Iterator[str])
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.codex¶

Parser for Codex’s NDJSON streaming format.

class ralph.agents.parsers.codex.CodexParser[source]¶

Bases: object

Parser for Codex’s NDJSON streaming output with robust delta accumulation.

Text deltas are accumulated into coherent blocks before emission, flushing on: - response.completed / turn.completed / message_stop (end of message) - \n\n paragraph boundary (incremental surfacing of long responses) - Iterator exhaustion (final flush via _flush_all_accumulators())

parse(lines)[source]¶

Parse Codex streaming NDJSON lines.

Parameters:: lines (Iterator[str])
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.gemini¶

Parser for Gemini’s SSE+JSON streaming format.

Gemini emits Server-Sent Events (SSE) where each event contains a JSON payload. This parser handles the SSE format and normalizes Gemini output to AgentOutputLine instances with robust delta accumulation.

class ralph.agents.parsers.gemini.GeminiParser[source]¶

Bases: object

Parser for Gemini’s SSE+JSON streaming output with robust delta accumulation.

Gemini uses SSE with data: lines containing JSON payloads. Each payload has a “type” field indicating what kind of content it carries. Text deltas are accumulated into coherent blocks before emission, flushing on: - done / stop / message_end (end of message) - \n\n paragraph boundary (incremental surfacing of long responses) - Iterator exhaustion (final flush via _flush_all_accumulators())

parse(lines)[source]¶

Parse Gemini SSE streaming lines.

Parameters:: lines (Iterator[str]) – Iterator of raw lines from Gemini stdout (SSE format).
Yields:: Normalized AgentOutputLine instances.
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.generic¶

Generic NDJSON parser for other agents.

This parser handles NDJSON output from agents that don’t have a dedicated parser. It attempts to extract text content and error information from common NDJSON formats, with robust delta accumulation for streaming text responses.

class ralph.agents.parsers.generic.GenericParser[source]¶

Bases: object

Generic NDJSON parser for unknown or simple agent formats.

This parser handles NDJSON by: 1. Parsing each line as JSON 2. Looking for common text fields (content, text, message, output) 3. Accumulating short text content and flushing on paragraph boundaries 4. Extracting error information 5. Falling back to raw line storage for unparseable content

Text deltas are accumulated into coherent blocks before emission, flushing on: - \n\n paragraph boundary (incremental surfacing of long responses) - Stop/done markers (end of message) - Iterator exhaustion (final flush via _flush_all_accumulators())

Short content (below threshold) that doesn’t end with \n\n is treated as a streaming delta and accumulated. Content at or above the threshold, or ending with \n\n, is emitted immediately.

Field priority for content extraction: 1. content, text, message, output, response, result (type=’text’) 2. thought, reasoning (type=’thinking’) — only when no higher-priority field matches

parse(lines)[source]¶

Parse generic streaming NDJSON lines.

Parameters:: lines (Iterator[str]) – Iterator of raw lines from agent stdout.
Yields:: Normalized AgentOutputLine instances.
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.opencode¶

Parser for OpenCode’s NDJSON streaming format.

class ralph.agents.parsers.opencode.OpenCodeParser[source]¶

Bases: object

Parser for OpenCode’s NDJSON streaming output with robust delta accumulation.

Text deltas are accumulated into coherent blocks before emission, flushing on: - step_finish / done (end of step/message) - \n\n paragraph boundary (incremental surfacing of long responses) - Iterator exhaustion (final flush via _flush_all_accumulators())

parse(lines)[source]¶

Parse OpenCode streaming NDJSON lines.

Parameters:: lines (Iterator[str])
Return type:: Iterator[AgentOutputLine]

ralph.agents.parsers.claude_interactive¶

Convert interactive Claude transcript lines into agent parser output.

class ralph.agents.parsers.claude_interactive.ClaudeInteractiveParser[source]¶

Bases: object

Convert interactive Claude transcript lines into AgentOutputLine events.

class ralph.agents.parsers.claude_interactive.ClaudeInteractiveTranscriptParser[source]¶

Bases: object

Extract semantic events from a normalized Claude interactive transcript.

class ralph.agents.parsers.claude_interactive.InteractiveTranscriptEvent(kind, text)[source]¶

Bases: object

Semantic event extracted from the interactive Claude transcript surface.

Parameters:

kind (str)
text (str)

ralph.agents.parsers.claude_interactive_transcript_parser¶

Semantic parser for VT-normalized Claude interactive transcripts.

class ralph.agents.parsers.claude_interactive_transcript_parser.ClaudeInteractiveTranscriptParser[source]¶

Bases: object

Extract semantic events from a normalized Claude interactive transcript.

ralph.agents.parsers.agent_output_line¶

Legacy normalized agent output line type.

class ralph.agents.parsers.agent_output_line.AgentOutputLine(type, content='', raw='', metadata=<factory>)[source]¶

Bases: object

Legacy normalised line extracted from agent NDJSON stream.

This type is preserved for backward compatibility while newer cross-layer visibility work adopts the typed activity model.

Parameters:

type (str)
content (str)
raw (str)
metadata (dict[str, object])

type¶

Type of the output line (text, tool_use, tool_result, error, etc.).

Type:: str

content¶

Text content of the line.

Type:: str

raw¶

Raw JSON string from the agent.

Type:: str

metadata¶

Additional metadata extracted from the line.

Type:: dict[str, object]

ralph.agents.parsers.interactive_transcript_event¶

Semantic event model for interactive Claude transcript parsing.

class ralph.agents.parsers.interactive_transcript_event.InteractiveTranscriptEvent(kind, text)[source]¶

Bases: object

Semantic event extracted from the interactive Claude transcript surface.

Parameters:

kind (str)
text (str)

ralph.agents.parsers.text_accumulator¶

Shared text delta accumulator for parser implementations.

class ralph.agents.parsers.text_accumulator.TextAccumulator(buffer='', raw_lines=<factory>)[source]¶

Bases: object

Shared delta accumulator for paragraph-boundary text flushing.

Parameters:

buffer (str)
raw_lines (list[str])

accumulate(text, raw, *, kind='text', keep_current_when_empty)[source]¶

Append text/raw and yield an AgentOutputLine if a paragraph boundary is reached.

Parameters:

text (str) – Text delta to append to the buffer.
raw (str) – Raw JSON line to track.
kind (str) – Output type for the emitted line (‘text’ or ‘thinking’).
keep_current_when_empty (bool) – When True, always keep the current raw line in the tail after a flush even if remaining buffer is empty (unconditional rule). When False, only keep it when remaining is non-empty.

Return type:

Iterator[AgentOutputLine]

flush(*, kind='text', require_strip=False)[source]¶

Yield remaining buffer content as an AgentOutputLine if non-empty, then reset.

Parameters:

kind (str) – Output type for the emitted line (‘text’ or ‘thinking’).
require_strip (bool) – When True, only emit if buffer.strip() is non-empty (for thinking accumulators that should suppress whitespace-only content).

Return type:

Iterator[AgentOutputLine]

ralph.agents.registry¶

Agent registry for managing available AI agents.

The registry loads agent configurations and resolves agent names to their executable commands and settings.

class ralph.agents.registry.AgentRegistry(*, ccs_defaults=None)[source]¶

Bases: object

Registry of available AI agents.

The registry maintains a mapping of agent names to their configurations. It supports loading agents from UnifiedConfig and resolving agent names at runtime.

Parameters:: ccs_defaults (CcsConfig | None)

agents¶: Dictionary mapping agent names to their configurations.

classmethod from_config(config)[source]¶

Create registry from UnifiedConfig.

Parameters:: config (UnifiedConfig) – Unified configuration containing agent definitions.
Returns:: Populated AgentRegistry instance.
Return type:: AgentRegistry

get(name)[source]¶

Get agent configuration by name.

Parameters:: name (str) – Agent name.
Returns:: AgentConfig if found, None otherwise.
Return type:: AgentConfig | None

get_command(name)[source]¶

Get the command for an agent.

Parameters:: name (str) – Agent name.
Returns:: Command string if agent found, None otherwise.
Return type:: str | None

list_agents()[source]¶

List all registered agent names.

Returns:: List of agent names.
Return type:: list[str]

register(name, config)[source]¶

Parameters:

name (str) – Agent name.
config (AgentConfig) – Agent configuration.

Return type:

None

validate()[source]¶

Validate all registered agents.

Returns:: List of validation error messages (empty if all valid).
Return type:: list[str]

ralph.agents.registry.builtin_agents()[source]¶

Return the built-in agent configurations keyed by agent name.

Return type:: dict[str, AgentConfig]

ralph.agents.subprocess_executor¶

SubprocessAgentExecutor — asyncio subprocess implementation of AgentExecutor.

class ralph.agents.subprocess_executor.SubprocessAgentExecutor(command, *, signal_bridge=None, cwd=None, extra_env=None, activity_router=None, raw_overflow_root=None, _pm=None)[source]¶

Bases: object

AgentExecutor that spawns a subprocess in its own process group.

Parameters:

command (Sequence[str])
signal_bridge (SignalBridge | None)
cwd (Path | None)
extra_env (Mapping[str, str] | None)
activity_router (ActivityRouter | None)
raw_overflow_root (Path | None)
_pm (ProcessManager | None)

ralph.agents.timeout_clock¶

Fake test clock for the agent timeout subsystem.

class ralph.agents.timeout_clock.Clock(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for wall-clock operations used by the timeout subsystem.

monotonic()[source]¶

Return current monotonic time in seconds.

Return type:: float

sleep(seconds)[source]¶

Pause execution for the given number of seconds.

Parameters:: seconds (float)
Return type:: None

wait_for_event(event, seconds)[source]¶

Wait up to seconds for event to be set.

Parameters:

event (threading.Event)
seconds (float)

Return type:

bool

class ralph.agents.timeout_clock.FakeClock(start=0.0)[source]¶

Bases: object

Test Clock: advances logical time synchronously without real waits.

Parameters:: start (float)

advance(seconds)[source]¶

Advance logical time by seconds without blocking.

Parameters:: seconds (float)
Return type:: None

class ralph.agents.timeout_clock.SystemClock(*args, **kwargs)[source]¶

Bases: Clock

Production Clock: uses real wall-clock time.

monotonic()[source]¶

Return current monotonic time in seconds.

Return type:: float

sleep(seconds)[source]¶

Pause execution for the given number of seconds.

Parameters:: seconds (float)
Return type:: None

wait_for_event(event, seconds)[source]¶

Wait up to seconds for event to be set.

Parameters:

event (Event)
seconds (float)

Return type:

bool

MCP¶

ralph.mcp¶

Public MCP bridge package.

This package groups together the Ralph-side MCP bridge, artifact helpers, transport abstractions, and access-mode helpers used by both the pipeline and standalone ralph-mcp runtime.

If you are navigating with pydoc, common entry points are MCPBridge for the bridge layer and ralph.mcp.server for standalone server helpers.

ralph.mcp.artifacts¶

Artifact storage and validation for MCP.

This sub-package contains the artifact store, file backend, and per-type validators (plan, development_result, commit_message) plus the audit adapter. These are the backends that MCP tool handlers call into.

ralph.mcp.artifacts.audit_adapter¶

Audit adapter utilities for MCP records.

class ralph.mcp.artifacts.audit_adapter.AgentSessionId(value)[source]¶

Bases: object

Convenience wrapper around a session identifier.

Parameters:: value (str)

class ralph.mcp.artifacts.audit_adapter.AuditCorrelation(run_id=None, generation=None, drain=None, policy_mode=None)[source]¶

Bases: object

Correlation metadata emitted with a Ralph audit record.

Parameters:

run_id (str | None)
generation (int | None)
drain (str | None)
policy_mode (str | None)

class ralph.mcp.artifacts.audit_adapter.AuditMetadata(event_type=McpAuditEventType.TOOL, details=None, correlation=<factory>)[source]¶

Bases: object

Extended metadata attached to an MCP audit record.

Parameters:

event_type (McpAuditEventType)
details (str | None)
correlation (McpAuditCorrelation)

class ralph.mcp.artifacts.audit_adapter.McpAuditCorrelation(run_id=None, generation=None, drain=None, policy_mode=None)[source]¶

Bases: object

Correlation metadata that comes from the MCP dispatch layer.

Parameters:

run_id (str | None)
generation (int | None)
drain (str | None)
policy_mode (PolicyMode | None)

class ralph.mcp.artifacts.audit_adapter.McpAuditEventType(*values)[source]¶

Bases: StrEnum

Enumeration of MCP audit event categories.

class ralph.mcp.artifacts.audit_adapter.McpAuditRecord(timestamp_nanos, session_id, tool_name, decision, path=None, capability=None, metadata=<factory>)[source]¶

Bases: object

Audit record emitted by the MCP server dispatch layer.

Parameters:

timestamp_nanos (int)
session_id (str)
tool_name (str)
decision (AccessDecision)
path (str | None)
capability (McpCapability | None)
metadata (AuditMetadata)

class ralph.mcp.artifacts.audit_adapter.RalphAuditRecord(session_id, timestamp, capability, outcome, description, duration_ms=None, result_status=None, event_type=None, correlation=None)[source]¶

Bases: object

Audit record format consumed by Ralph’s audit trail.

Parameters:

session_id (AgentSessionId)
timestamp (int)
capability (RalphCapability)
outcome (PolicyOutcome)
description (str)
duration_ms (int | None)
result_status (str | None)
event_type (str | None)
correlation (AuditCorrelation | None)

class ralph.mcp.artifacts.audit_adapter.RalphAuditSinkAdapter[source]¶

Bases: object

Adapter that buffers Ralph audit records produced by MCP.

drain_records()[source]¶

Return buffered records and clear the buffer.

Return type:: list[RalphAuditRecord]

emit(record)[source]¶

Store a converted audit record in the buffer.

Parameters:: record (McpAuditRecord)
Return type:: None

flush()[source]¶

No-op flush since records are held in memory.

Return type:: None

ralph.mcp.artifacts.audit_adapter.outcome_from_decision(decision)[source]¶

Convert an access decision into a policy outcome.

Parameters:: decision (AccessDecision)
Return type:: PolicyOutcome

ralph.mcp.artifacts.audit_adapter.resolve_audit_capability(record)[source]¶

Map MCP capability to Ralph capability or fall back to workspace read.

Parameters:: record (McpAuditRecord)
Return type:: Capability

ralph.mcp.artifacts.bridge¶

MCP bridge.

Bridges Ralph’s phase system with MCP (Model Context Protocol) clients. Exposes tools for agent interactions, artifact submission, and state queries.

class ralph.mcp.artifacts.bridge.BridgeArtifactDeps(backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso=<function _utc_now_iso>)[source]¶

Bases: object

Dependencies injected into bridge artifact operations.

Parameters:

backend (FileBackend)
now_iso (Callable[[], str])

class ralph.mcp.artifacts.bridge.BridgeConfig(artifact_dir=PosixPath('.agent/artifacts'), workspace_root=PosixPath('.'), transport=None, artifact_deps=<factory>)[source]¶

Bases: object

Configuration for MCP bridge.

Parameters:

artifact_dir (Path)
workspace_root (Path)
transport (MCPTransport | None)
artifact_deps (BridgeArtifactDeps)

exception ralph.mcp.artifacts.bridge.BridgeError[source]¶

Bases: Exception

Raised when bridge operations fail.

class ralph.mcp.artifacts.bridge.MCPBridge(config)[source]¶

Bases: object

MCP bridge for Ralph.

Bridges the phase system with MCP by exposing tools to agents, managing artifact lifecycle, and handling MCP protocol messages.

Parameters:: config (BridgeConfig)

async close()[source]¶

Close the bridge and transport.

Return type:: None

get_artifact_mcp(name)[source]¶

Get an artifact via MCP.

Parameters:: name (str) – Artifact name.
Returns:: Artifact data.
Return type:: dict[str, object]

async handle_message(message)[source]¶

Handle an incoming MCP message.

Parameters:: message (MCPMessage) – The MCP message to process.
Returns:: Optional response message.
Return type:: MCPMessage | None

list_artifacts_mcp()[source]¶

List all artifacts via MCP.

Returns:: List of artifacts.
Return type:: dict[str, object]

register_tool(name, description, input_schema, handler)[source]¶

Parameters:

name (str) – Tool name.
description (str) – Tool description.
input_schema (dict[str, object]) – JSON schema for input validation.
handler (_ToolHandler) – Function to call when tool is invoked.

Return type:

None

async run()[source]¶

Run the bridge message loop.

Return type:: None

start()[source]¶

Start the MCP bridge.

Return type:: None

submit_artifact_mcp(name, artifact_type, content, metadata=None)[source]¶

Submit an artifact via MCP.

Parameters:

name (str) – Artifact name.
artifact_type (str) – Type of artifact.
content (dict[str, object]) – Artifact content.
metadata (dict[str, object] | None) – Optional metadata.

Returns:

Artifact submission result.

Return type:

dict[str, object]

tool_called(name, arguments)[source]¶

Handle a tool call from an MCP client.

Parameters:

name (str) – Tool name.
arguments (dict[str, object]) – Tool arguments.

Returns:

Tool result as a dictionary.

Raises:

BridgeError – If tool is not found or execution fails.

Return type:

dict[str, object]

ralph.mcp.artifacts.commit_message¶

Commit-message artifact helpers.

Canonical commit messages are stored as MCP-style JSON artifacts in .agent/tmp/commit_message.json. The commit artifact content follows a structured schema with either a commit or skip variant. A plain-text mirror in .agent/tmp/commit-message.txt is maintained for CLI compatibility.

ralph.mcp.artifacts.commit_message.commit_message_artifact_path(repo_root)[source]¶

Return the canonical artifact JSON path for the given repo root.

Parameters:: repo_root (Path)
Return type:: Path

ralph.mcp.artifacts.commit_message.commit_message_text_path(repo_root)[source]¶

Return the plain-text mirror path for commit messages.

Parameters:: repo_root (Path)
Return type:: Path

ralph.mcp.artifacts.commit_message.delete_commit_message_artifacts(repo_root, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Remove all commit message artifacts and legacy stale files.

Parameters:

repo_root (Path)
backend (FileBackend)

Return type:

None

ralph.mcp.artifacts.commit_message.normalize_commit_message_content(content)[source]¶

Validate and normalize a commit message payload to a canonical dict form.

Parameters:: content (str | dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.commit_message.read_commit_message_artifact(repo_root, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Read the commit message from the canonical artifact, falling back to the text file.

Parameters:

repo_root (Path)
backend (FileBackend)

Return type:

str | None

ralph.mcp.artifacts.commit_message.read_commit_message_from_path(message_file, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Read a commit message from an arbitrary file path (JSON or plain text).

Parameters:

message_file (Path)
backend (FileBackend)

Return type:

str | None

ralph.mcp.artifacts.commit_message.read_commit_message_payload_from_path(message_file, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Read and normalize a commit message payload from JSON or plain text.

Parameters:

message_file (Path)
backend (FileBackend)

Return type:

dict[str, object] | None

ralph.mcp.artifacts.commit_message.render_commit_message_content(content)[source]¶

Render normalized commit message content as a plain-text commit message string.

Parameters:: content (dict[str, object])
Return type:: str

ralph.mcp.artifacts.commit_message.write_commit_message_artifact(repo_root, message, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso=<function _now_iso>)[source]¶

Persist a commit message as both a JSON artifact and a plain-text file.

Parameters:

repo_root (Path)
message (str | dict[str, object])
backend (FileBackend)
now_iso (Callable[[], str])

Return type:

None

ralph.mcp.artifacts.development_result¶

Structured development_result artifact validation helpers.

class ralph.mcp.artifacts.development_result.AnalysisItemProof(*, how_to_fix_item, proof)[source]¶

Bases: BaseModel

Evidence that a prior analysis item was addressed.

Parameters:

how_to_fix_item (Annotated[str, MinLen(min_length=1)])
proof (Annotated[str, MinLen(min_length=1)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.development_result.Continuation(*, prior_session_id)[source]¶

Bases: BaseModel

Reference to a prior session when a development result is partial.

Parameters:: prior_session_id (Annotated[str, MinLen(min_length=1)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.development_result.DevelopmentResult(*, status, summary, files_changed, plan_items_proven=<factory>, analysis_items_addressed=<factory>, next_steps=None, continuation=None)[source]¶

Bases: BaseModel

Validated schema for a development_result artifact.

Parameters:

status (Annotated[str, MinLen(min_length=1)])
summary (Annotated[str, MinLen(min_length=1)])
files_changed (Annotated[str, MinLen(min_length=1)])
plan_items_proven (list[PlanItemProof])
analysis_items_addressed (list[AnalysisItemProof])
next_steps (str | None)
continuation (Continuation | None)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception ralph.mcp.artifacts.development_result.DevelopmentResultValidationError[source]¶

Bases: ValueError

Raised when a development_result artifact is malformed.

class ralph.mcp.artifacts.development_result.PlanItemProof(*, plan_item, proof)[source]¶

Bases: BaseModel

Evidence that a plan item was completed.

Parameters:

plan_item (Annotated[str, MinLen(min_length=1)])
proof (Annotated[str, MinLen(min_length=1)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.mcp.artifacts.development_result.normalize_development_result_content(content)[source]¶

Validate and normalize a raw development_result content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.file_backend¶

Shared file backend abstractions for MCP persistence.

class ralph.mcp.artifacts.file_backend.FileBackend(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for filesystem I/O required by artifact persistence.

class ralph.mcp.artifacts.file_backend.PathFileBackend[source]¶

Bases: object

Concrete FileBackend implementation backed by pathlib.Path operations.

ralph.mcp.artifacts.format_docs¶

Bundled dumb-proof Markdown reference docs for non-plan artifact submission.

ralph.mcp.artifacts.format_docs.format_doc_workspace_path(artifact_type)[source]¶

Return the workspace-relative path for an artifact format doc.

Parameters:: artifact_type (str)
Return type:: str

ralph.mcp.artifacts.format_docs.format_index_workspace_path()[source]¶

Return the workspace-relative path for the artifact formats index doc.

Return type:: str

ralph.mcp.artifacts.format_docs.has_format_doc(artifact_type)[source]¶

Return True if a bundled format doc exists for the given artifact type.

Parameters:: artifact_type (str)
Return type:: bool

ralph.mcp.artifacts.format_docs.load_bundled_format_doc(artifact_type)[source]¶

Load a bundled Markdown format doc for the given artifact type, or None if unknown.

Parameters:: artifact_type (str)
Return type:: str | None

ralph.mcp.artifacts.format_docs.load_bundled_format_index()[source]¶

Load the bundled artifact formats index doc.

Return type:: str

ralph.mcp.artifacts.format_docs.materialize_all_format_docs(workspace_root, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Write all bundled format docs and the index into the workspace.

Parameters:

workspace_root (Path)
backend (FileBackend)

Return type:

list[str]

ralph.mcp.artifacts.format_docs.materialize_format_doc(workspace_root, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Write a bundled format doc into the workspace and return its relative path.

Parameters:

workspace_root (Path)
artifact_type (str)
backend (FileBackend)

Return type:

str | None

ralph.mcp.artifacts.format_docs.materialize_format_index(workspace_root, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Materialize the bundled artifact formats index doc to workspace.

Returns the relative path to the materialized index file.

Parameters:

workspace_root (Path)
backend (FileBackend)

Return type:

str

ralph.mcp.artifacts.handoffs¶

Agent/user-facing Markdown handoff helpers.

Structured JSON artifacts remain Ralph’s machine-readable source of truth for validation and routing. This module mirrors selected artifact payloads into Markdown files so downstream agents and users consume a stable, human-readable handoff instead of raw JSON.

ralph.mcp.artifacts.handoffs.delete_markdown_handoff(workspace_root, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Remove a mirrored Markdown handoff if the artifact write rolls back.

Parameters:

workspace_root (Path)
artifact_type (str)
backend (FileBackend)

Return type:

None

ralph.mcp.artifacts.handoffs.ensure_markdown_handoff_from_artifact(workspace_root, artifact_type, artifact_content, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Ensure a Markdown handoff exists from a persisted JSON artifact payload.

Parameters:

workspace_root (Path)
artifact_type (str)
artifact_content (str)
backend (FileBackend)

Return type:

str | None

ralph.mcp.artifacts.handoffs.handoff_path_for_artifact(artifact_type)[source]¶

Return the Markdown handoff path for an artifact type, if any.

Parameters:: artifact_type (str)
Return type:: str | None

ralph.mcp.artifacts.handoffs.render_markdown_handoff(artifact_type, content)[source]¶

Render an artifact payload into the Markdown handoff users/agents consume.

Parameters:

artifact_type (str)
content (Mapping[str, object])

Return type:

str

ralph.mcp.artifacts.handoffs.sync_markdown_handoff(workspace_root, artifact_type, content, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Write the Markdown handoff for a machine artifact and return its path.

Parameters:

workspace_root (Path)
artifact_type (str)
content (Mapping[str, object])
backend (FileBackend)

Return type:

str | None

ralph.mcp.artifacts.history¶

Artifact history archival and indexing.

When a phase’s artifact_history policy has enabled=True, the runtime archives the current canonical artifact JSON and its Markdown handoff into a stable history directory before overwriting them. This lets planning agents inspect prior failed plans and analysis decisions across re-planning loops.

Layout under .agent/artifacts/:

history/<artifact_type>/ – history root for a type: <timestamp>_<artifact_type>.json – archived canonical JSON <timestamp>_<artifact_type>.md – archived Markdown handoff (when present) index.md – human-readable summary of archived entries

The canonical latest files (.agent/artifacts/plan.json, .agent/PLAN.md, etc.) are never moved here — they remain the authoritative current state. History contains only prior versions that were overwritten.

ralph.mcp.artifacts.history.archive_artifact_before_overwrite(artifact_dir, workspace_root, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso)[source]¶

Archive the current canonical artifact files before they are overwritten.

Reads the current canonical JSON artifact and its Markdown handoff (if any), writes them into the history directory under a timestamped prefix, then rebuilds the history index.

Parameters:

artifact_dir (Path) – The artifacts directory (e.g. .agent/artifacts/).
workspace_root (Path) – Workspace root (used to locate Markdown handoff files).
artifact_type (str) – The artifact type identifier (e.g. ‘plan’).
backend (FileBackend) – File backend for I/O.
now_iso (Callable[[], str]) – Callable returning the current timestamp as an ISO 8601 string.

Returns:

List of Paths of files created by this operation (JSON and MD archives, NOT the index). The caller can use these paths to roll back the archive.

Return type:

list[Path]

ralph.mcp.artifacts.history.clear_artifact_history(artifact_dir, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Remove all archived history files for an artifact type.

Deletes all timestamped archive files and the index. The history directory itself is left in place to avoid filesystem churn on repeated planning cycles.

Parameters:

artifact_dir (Path)
artifact_type (str)
backend (FileBackend)

Return type:

None

ralph.mcp.artifacts.history.history_dir_for_artifact(artifact_dir, artifact_type)[source]¶

Return the history directory for an artifact type.

Parameters:

artifact_dir (Path)
artifact_type (str)

Return type:

Path

ralph.mcp.artifacts.history.history_index_path(artifact_dir, artifact_type)[source]¶

Return the path to the history index file for an artifact type.

Parameters:

artifact_dir (Path)
artifact_type (str)

Return type:

Path

ralph.mcp.artifacts.history.rebuild_history_index(artifact_dir, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Rebuild the history index from files present in the history directory.

Always writes a fresh index.md derived from directory contents so the index stays consistent with the actual archived files regardless of rollback state.

Parameters:

artifact_dir (Path)
artifact_type (str)
backend (FileBackend)

Return type:

None

ralph.mcp.artifacts.history.snapshot_current_artifact(artifact_dir, workspace_root, artifact_type, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso)[source]¶

Snapshot the current canonical artifact and handoff into history.

Unlike archive-before-overwrite, this records the current successful artifact immediately after submission so history exists from the first completed phase.

Parameters:

artifact_dir (Path)
workspace_root (Path)
artifact_type (str)
backend (FileBackend)
now_iso (Callable[[], str])

Return type:

list[Path]

ralph.mcp.artifacts.plan¶

Structured planning artifact validation helpers.

ralph.mcp.artifacts.plan.plan_schema¶

Structured Pydantic schema models for plan artifacts.

class ralph.mcp.artifacts.plan.plan_schema.CriticalFiles(*, primary_files, reference_files=<factory>)[source]¶

Bases: BaseModel

Parameters:

primary_files (Annotated[list[CriticalPrimaryFile], MinLen(min_length=1)])
reference_files (list[ReferenceFile])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.CriticalPrimaryFile(*, path, action, estimated_changes=None)[source]¶

Bases: BaseModel

Parameters:

path (Annotated[str, MinLen(min_length=1)])
action (Literal['create', 'modify', 'delete'])
estimated_changes (str | None)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.EditArea(*, paths=<factory>, directories=<factory>)[source]¶

Bases: BaseModel

Parameters:

paths (list[str])
directories (list[str])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.ParallelPlanItem(*, id, description, edit_area, depends_on=<factory>)[source]¶

Bases: BaseModel

A unit of parallelisable work with dependency tracking.

Parameters:

id (Annotated[str, MinLen(min_length=1)])
description (Annotated[str, MinLen(min_length=1)])
edit_area (EditArea)
depends_on (list[str])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.PlanStep(*, number, title, content, step_type='file_change', priority=None, targets=<factory>, location=None, rationale=None, depends_on=<factory>)[source]¶

Bases: BaseModel

Parameters:

number (Annotated[int, Ge(ge=1)])
title (Annotated[str, MinLen(min_length=1)])
content (Annotated[str, MinLen(min_length=1)])
step_type (Literal['file_change', 'action', 'research'])
priority (Literal['critical', 'high', 'medium', 'low'] | None)
targets (list[StepTarget])
location (str | None)
rationale (str | None)
depends_on (list[int])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.ReferenceFile(*, path, purpose)[source]¶

Bases: BaseModel

Parameters:

path (Annotated[str, MinLen(min_length=1)])
purpose (Annotated[str, MinLen(min_length=1)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.RiskMitigation(*, risk, mitigation, severity=None)[source]¶

Bases: BaseModel

Parameters:

risk (Annotated[str, MinLen(min_length=1)])
mitigation (Annotated[str, MinLen(min_length=1)])
severity (Literal['low', 'medium', 'high', 'critical'] | None)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.ScopeItem(*, text, count=None, category=None)[source]¶

Bases: BaseModel

Parameters:

text (Annotated[str, MinLen(min_length=1)])
count (str | None)
category (str | None)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.SkillsMcp(*, skills=<factory>, mcps=<factory>)[source]¶

Bases: BaseModel

Parameters:

skills (list[str])
mcps (list[str])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.StepTarget(*, path, action)[source]¶

Bases: BaseModel

Parameters:

path (Annotated[str, MinLen(min_length=1)])
action (Literal['create', 'modify', 'delete', 'read', 'reference'])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.Summary(*, context, scope_items)[source]¶

Bases: BaseModel

Parameters:

context (Annotated[str, MinLen(min_length=1)])
scope_items (Annotated[list[ScopeItem], MinLen(min_length=3)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ralph.mcp.artifacts.plan.plan_schema.VerificationStep(*, method, expected_outcome)[source]¶

Bases: BaseModel

Parameters:

method (Annotated[str, MinLen(min_length=1)])
expected_outcome (Annotated[str, MinLen(min_length=1)])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ralph.mcp.artifacts.policy_outcomes¶

Shared helpers for interpreting MCP approval outcomes.

ralph.mcp.artifacts.policy_outcomes.is_policy_approved(outcome)[source]¶

Return True if the given policy outcome represents an approval decision.

Parameters:: outcome (object | None)
Return type:: bool

ralph.mcp.artifacts.store¶

MCP artifact handling.

Provides artifact submission, retrieval, and management for MCP interactions. Artifacts are JSON files stored in the workspace’s .agent/artifacts/ directory.

class ralph.mcp.artifacts.store.Artifact(name, artifact_type, content, created_at=<factory>, updated_at=<factory>, metadata=<factory>)[source]¶

Bases: object

Represents an MCP artifact.

Parameters:

name (str)
artifact_type (str)
content (dict[str, object])
created_at (str)
updated_at (str)
metadata (dict[str, object])

name¶

Unique artifact name.

Type:: str

artifact_type¶

Type identifier (e.g., “planning”, “code”, “review”).

Type:: str

content¶

Artifact content as a dictionary.

Type:: dict[str, object]

created_at¶

ISO timestamp when artifact was created.

Type:: str

updated_at¶

ISO timestamp when artifact was last updated.

Type:: str

metadata¶

Optional metadata dictionary.

Type:: dict[str, object]

classmethod from_dict(data)[source]¶

Create an artifact from a dictionary.

Parameters:: data (dict[str, object])
Return type:: Artifact

to_dict()[source]¶

Convert artifact to dictionary for JSON serialization.

Return type:: dict[str, object]

exception ralph.mcp.artifacts.store.ArtifactExistsError[source]¶

Bases: ArtifactError

Raised when attempting to create an artifact that already exists.

exception ralph.mcp.artifacts.store.ArtifactNotFoundError[source]¶

Bases: ArtifactError

Raised when an artifact is not found.

class ralph.mcp.artifacts.store.ArtifactPersistence(backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso=<function _utc_now_iso>)[source]¶

Bases: object

Backend and clock dependencies for artifact persistence operations.

Parameters:

backend (FileBackend)
now_iso (Callable[[], str])

class ralph.mcp.artifacts.store.ArtifactSubmitOptions(metadata=None, overwrite=False, persistence=<factory>)[source]¶

Bases: object

Options for artifact submission.

Parameters:

metadata (dict[str, object] | None)
overwrite (bool)
persistence (ArtifactPersistence)

class ralph.mcp.artifacts.store.ArtifactUpdateOptions(content=None, metadata=None, persistence=<factory>)[source]¶

Bases: object

Options for updating an existing artifact.

Parameters:

content (dict[str, object] | None)
metadata (dict[str, object] | None)
persistence (ArtifactPersistence)

ralph.mcp.artifacts.store.delete_artifact(artifact_dir, name, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Delete an artifact.

Parameters:

artifact_dir (Path) – Directory where artifacts are stored.
name (str) – Artifact name.
backend (FileBackend)

Raises:

ArtifactNotFoundError – If artifact does not exist.

Return type:

None

ralph.mcp.artifacts.store.get_artifact(artifact_dir, name, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Retrieve an artifact by name.

Parameters:

artifact_dir (Path) – Directory where artifacts are stored.
name (str) – Artifact name.
backend (FileBackend)

Returns:

The artifact.

Raises:

ArtifactNotFoundError – If artifact does not exist.

Return type:

Artifact

ralph.mcp.artifacts.store.list_artifacts(artifact_dir, *, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

List all artifacts in the directory.

Parameters:

artifact_dir (Path) – Directory where artifacts are stored.
backend (FileBackend)

Returns:

List of artifacts.

Return type:

list[Artifact]

ralph.mcp.artifacts.store.submit_artifact(artifact_dir, name, artifact_type, content, options=None)[source]¶

Submit a new artifact.

Parameters:

artifact_dir (Path) – Directory to store artifacts (e.g., .agent/artifacts/).
name (str) – Unique artifact name.
artifact_type (str) – Type of artifact.
content (dict[str, object]) – Artifact content.
options (ArtifactSubmitOptions | None) – Optional submission options.

Returns:

The created artifact.

Raises:

ArtifactExistsError – If artifact exists and overwrite is False.

Return type:

Artifact

ralph.mcp.artifacts.store.update_artifact(artifact_dir, name, options=None)[source]¶

Update an existing artifact.

Parameters:

artifact_dir (Path) – Directory where artifacts are stored.
name (str) – Artifact name.
content – New content (merged with existing).
metadata – New metadata (merged with existing).
options (ArtifactUpdateOptions | None)

Returns:

The updated artifact.

Raises:

ArtifactNotFoundError – If artifact does not exist.

Return type:

Artifact

ralph.mcp.artifacts.smoke_test_result¶

Structured smoke_test_result artifact validation helpers.

exception ralph.mcp.artifacts.smoke_test_result.SmokeTestResultValidationError[source]¶

Bases: ValueError

Raised when a smoke_test_result artifact is malformed.

ralph.mcp.artifacts.smoke_test_result.normalize_smoke_test_result_content(content)[source]¶

Validate and normalize a raw smoke_test_result content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.smoke_test_result.read_smoke_test_result_artifact(repo_root)[source]¶

Read the persisted smoke_test_result artifact content from the workspace.

Parameters:: repo_root (Path)
Return type:: dict[str, object] | None

ralph.mcp.artifacts.product_spec¶

Structured product_spec artifact validation helpers and PROMPT.md rendering.

class ralph.mcp.artifacts.product_spec.ProductSpec(*, title, scope, goals, users, constraints=<factory>, success_criteria, product_behavior=<factory>, ux_ui_requirements=<factory>, scope_boundaries=<factory>, open_questions=<factory>)[source]¶

Bases: BaseModel

Validated schema for a product_spec artifact.

Parameters:

title (Annotated[str, MinLen(min_length=1)])
scope (Annotated[str, MinLen(min_length=1)])
goals (Annotated[list[str], MinLen(min_length=1)])
users (Annotated[list[str], MinLen(min_length=1)])
constraints (list[str])
success_criteria (Annotated[list[str], MinLen(min_length=1)])
product_behavior (list[str])
ux_ui_requirements (list[str])
scope_boundaries (list[str])
open_questions (list[str])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception ralph.mcp.artifacts.product_spec.ProductSpecValidationError[source]¶

Bases: Exception

Raised when product_spec content fails validation.

ralph.mcp.artifacts.product_spec.normalize_product_spec_content(content)[source]¶

Validate and normalize a raw product_spec content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.product_spec.read_product_spec_artifact(repo_root)[source]¶

Read the persisted product_spec artifact content from the workspace.

Parameters:: repo_root (Path)
Return type:: dict[str, object] | None

ralph.mcp.artifacts.product_spec.render_product_spec_as_prompt(spec)[source]¶

Render a product_spec dict as a PROMPT.md-formatted string.

The output follows the canonical PROMPT.md structure: - # Goal: title (bold) + scope paragraph - ## Context: goals, users, constraints, product_behavior, ux_ui_requirements - ## Acceptance criteria: success_criteria bullets - ## Notes: scope_boundaries + open_questions (only if non-empty)

Parameters:: spec (dict[str, object])
Return type:: str

ralph.mcp.artifacts.typed_artifacts¶

Structured validation for typed non-plan artifact payloads.

Covers: issues, fix_result, and analysis decision artifacts.

exception ralph.mcp.artifacts.typed_artifacts.TypedArtifactValidationError[source]¶

Bases: ValueError

Raised when a typed artifact payload is malformed.

ralph.mcp.artifacts.typed_artifacts.normalize_analysis_decision_content(content, *, allowed_statuses=None)[source]¶

Validate and normalize an analysis decision artifact content dict.

Parameters:

content (dict[str, object])
allowed_statuses (Collection[str] | None)

Return type:

dict[str, object]

ralph.mcp.artifacts.typed_artifacts.normalize_commit_cleanup_content(content)[source]¶

Validate and normalize a raw commit_cleanup artifact content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.typed_artifacts.normalize_fix_result_content(content)[source]¶

Validate and normalize a raw fix_result artifact content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.artifacts.typed_artifacts.normalize_issues_content(content)[source]¶

Validate and normalize a raw issues artifact content dict.

Parameters:: content (dict[str, object])
Return type:: dict[str, object]

ralph.mcp.protocol¶

Shared MCP protocol plumbing.

This sub-package contains transport, session, and capability-mapping code used by both the Ralph MCP server (Ralph → agents) and the upstream client (Ralph → external MCPs). Keeping these in a neutral location avoids import cycles between server/ and upstream/.

ralph.mcp.protocol.capability_mapping¶

MCP capability mapping for Ralph sessions.

Ports the Rust capability-mapping layer used to translate session drain and policy outcomes into MCP access-control decisions.

class ralph.mcp.protocol.capability_mapping.AccessDecision(allowed, reason=None, code=None)[source]¶

Bases: object

Result of an MCP access decision.

Parameters:

allowed (bool)
reason (str | None)
code (AccessDeniedCode | None)

classmethod allow()[source]¶

Build an allow decision.

Return type:: AccessDecision

classmethod deny(reason, code)[source]¶

Build a deny decision.

Parameters:

reason (str)
code (AccessDeniedCode)

Return type:

AccessDecision

is_allowed()[source]¶

Return whether access is allowed.

Return type:: bool

class ralph.mcp.protocol.capability_mapping.AccessDeniedCode(*values)[source]¶

Bases: StrEnum

Categorical access-denial codes.

class ralph.mcp.protocol.capability_mapping.AccessMode(*values)[source]¶

Bases: StrEnum

Server access mode for MCP tool dispatch.

allows_write()[source]¶

Return whether this access mode allows write operations.

Return type:: bool

class ralph.mcp.protocol.capability_mapping.Capability(*values)[source]¶

Bases: StrEnum

Internal Ralph capability vocabulary.

class ralph.mcp.protocol.capability_mapping.DrainClass(*values)[source]¶

Bases: StrEnum

Drain class used for capability defaults.

allows_write()[source]¶

Return whether this drain class allows write operations.

Return type:: bool

class ralph.mcp.protocol.capability_mapping.McpCapability(*values)[source]¶

Bases: StrEnum

Typed MCP capability vocabulary.

class ralph.mcp.protocol.capability_mapping.PolicyMode(*values)[source]¶

Bases: StrEnum

Runtime policy mode enforced by the MCP server.

access_mode()[source]¶

Return the matching access mode.

Return type:: AccessMode

class ralph.mcp.protocol.capability_mapping.PolicyOutcome(status, reason=None, restriction=None)[source]¶

Bases: object

Normalized policy outcome payload.

Parameters:

status (PolicyOutcomeStatus)
reason (str | None)
restriction (str | None)

class ralph.mcp.protocol.capability_mapping.PolicyOutcomeStatus(*values)[source]¶

Bases: StrEnum

Normalized policy outcome status.

class ralph.mcp.protocol.capability_mapping.SessionDrain(*values)[source]¶

Bases: StrEnum

Pipeline drain identity for a Ralph session.

ralph.mcp.protocol.capability_mapping.check_mcp_capability_policy(capability, ephemeral, tracked, mapped_outcome)[source]¶

Decide access for an MCP capability from session policy outcomes.

Parameters:

capability (McpCapability | str)
ephemeral (object)
tracked (object)
mapped_outcome (tuple[TypeAliasForwardRef('ralph.mcp.protocol.capability_mapping.Capability') | str, object] | None)

Return type:

AccessDecision

ralph.mcp.protocol.capability_mapping.drain_class_for_session(drain, agents_policy=None)[source]¶

Classify a session drain into its drain class.

Resolution is policy-defined only: callers must supply agents_policy and the drain must be declared there with an explicit drain_class.

Parameters:

drain (SessionDrain | str)
agents_policy (AgentsPolicy | None)

Return type:

DrainClass

ralph.mcp.protocol.capability_mapping.drain_to_access_mode(drain, agents_policy=None)[source]¶

Determine the MCP access mode for a session drain.

Parameters:

drain (SessionDrain | str)
agents_policy (AgentsPolicy | None)

Return type:

AccessMode

ralph.mcp.protocol.capability_mapping.drain_to_policy_mode(drain, agents_policy=None)[source]¶

Map a session drain to the matching policy mode.

Accepts any policy-declared drain name by resolving its class through drain_class_for_session. DrainClass and PolicyMode share the same vocabulary, so the mapping is a direct value lookup.

Parameters:

drain (SessionDrain | str)
agents_policy (AgentsPolicy | None)

Return type:

PolicyMode

ralph.mcp.protocol.capability_mapping.evaluate_mapped_capability(capability, mapped_outcome)[source]¶

Evaluate access for a capability that maps directly to a Ralph capability.

Parameters:

capability (McpCapability | str)
mapped_outcome (tuple[TypeAliasForwardRef('ralph.mcp.protocol.capability_mapping.Capability') | str, object] | None)

Return type:

AccessDecision

ralph.mcp.protocol.capability_mapping.evaluate_workspace_write(ephemeral, tracked)[source]¶

Evaluate the composite workspace-write policy.

Parameters:

ephemeral (object)
tracked (object)

Return type:

AccessDecision

ralph.mcp.protocol.capability_mapping.lookup_ralph_capability(capability)[source]¶

Look up the Ralph capability mapped from an MCP capability.

Parameters:: capability (McpCapability | str)
Return type:: TypeAliasForwardRef(‘ralph.mcp.protocol.capability_mapping.Capability’) | None

ralph.mcp.protocol.capability_mapping.policy_from_outcome(outcome)[source]¶

Convert a Ralph policy outcome to an MCP access decision.

Parameters:: outcome (object)
Return type:: AccessDecision

ralph.mcp.protocol.env¶

Shared Ralph MCP environment variable names.

class ralph.mcp.protocol.env.McpEnvVar(*values)[source]¶

Bases: StrEnum

Environment variable names used to configure the Ralph MCP connection.

ralph.mcp.protocol.session¶

Shared session metadata for standalone Ralph MCP processes.

class ralph.mcp.protocol.session.AgentSession(session_id, run_id, drain, capabilities=<factory>, policy_flags=None, created_at=<factory>, parallel_worker=False, edit_area_result=None, worker_artifact_dir=None, worker_namespace=None, allowed_roots=<factory>, media_manifest=<factory>, model_identity=MultimodalModelIdentity(provider='unknown', model_id=None, transport=None), stored_capability_profile=None)[source]¶

Bases: object

Lightweight session holder used by standalone Ralph MCP tooling.

Parameters:

session_id (str)
run_id (str)
drain (str)
capabilities (set[str])
policy_flags (set[str] | None)
created_at (float)
parallel_worker (bool)
edit_area_result (object)
worker_artifact_dir (Path | None)
worker_namespace (Path | None)
allowed_roots (tuple[Path, ...])
media_manifest (MediaManifest)
model_identity (MultimodalModelIdentity)
stored_capability_profile (ResolvedCapabilityProfile | None)

property capability_profile: ResolvedCapabilityProfile¶: Return the stored profile when present, otherwise resolve from model_identity.

class ralph.mcp.protocol.session.MediaManifest(_entries=<factory>, _identity_index=<factory>)[source]¶

Bases: object

Session-scoped manifest of all multimodal resource references.

Parameters:

_entries (dict[str, ManifestEntry])
_identity_index (dict[str, str])

add(*, title, mime_type, modality, raw_bytes, extras=None)[source]¶

Add or replace an artifact and return its manifest entry.

Parameters:

title (str)
mime_type (str)
modality (str)
raw_bytes (bytes)
extras (MediaEntryExtras | None)

Return type:

ManifestEntry

get(artifact_id)[source]¶

Retrieve a manifest entry by artifact_id, or None if not found.

Parameters:: artifact_id (str)
Return type:: ManifestEntry | None

is_empty()[source]¶

Return True if no artifacts have been stored.

Return type:: bool

list_entries()[source]¶

Return all manifest entries in insertion order.

Return type:: list[ManifestEntry]

ralph.mcp.protocol.session.session_has_capability(granted, requested)[source]¶

Return True if the requested capability is present in the granted set.

Parameters:

granted (set[str])
requested (str)

Return type:

bool

ralph.mcp.protocol.startup¶

MCP server startup helpers ported from ralph-workflow/src/mcp_server/startup.rs.

class ralph.mcp.protocol.startup.HeartbeatPolicy(interval)[source]¶

Bases: object

Supervision interval configuration for active MCP health monitoring.

Parameters:: interval (timedelta)

class ralph.mcp.protocol.startup.HttpEndpointTarget(address: 'tuple[str, int]', host_header: 'str', path: 'str')[source]¶

Bases: object

Parameters:

address (tuple[str, int])
host_header (str)
path (str)

ralph.mcp.protocol.startup.HttpJsonRpcWithSessionFn¶: alias of object

ralph.mcp.protocol.startup.HttpPostFn¶: alias of object

exception ralph.mcp.protocol.startup.PreflightError[source]¶

Bases: Exception

Base class for MCP preflight failures.

exception ralph.mcp.protocol.startup.SessionBridgeError[source]¶

Bases: Exception

Raised when the session bridge fails to start or preflight fails.

ralph.mcp.protocol.startup.access_mode_for_drain(drain, agents_policy=None)[source]¶

Expose the MCP access mode mapping from the Rust startup module.

Parameters:

drain (str)
agents_policy (AgentsPolicy | None)

Return type:

AccessMode

ralph.mcp.protocol.startup.heartbeat_policy_from_env(env=None)[source]¶

Return the configured MCP supervision check interval.

Parameters:: env (Mapping[str, str] | None)
Return type:: HeartbeatPolicy

ralph.mcp.protocol.startup.mcp_preflight_timeout_from_env(env=None)[source]¶

Return the configured MCP preflight timeout duration.

Parameters:: env (Mapping[str, str] | None)
Return type:: timedelta

ralph.mcp.protocol.startup.mcp_probe_timeout_from_env(env=None)[source]¶

Return the configured MCP responsiveness probe timeout duration.

Parameters:: env (Mapping[str, str] | None)
Return type:: timedelta

ralph.mcp.protocol.startup.parse_tcp_endpoint(endpoint)[source]¶

Parse a tcp:// endpoint URL into a (host, port) tuple.

Parameters:: endpoint (str)
Return type:: tuple[str, int]

ralph.mcp.protocol.startup.preflight_http_mcp_server_tools(endpoint, required_tools, timeout)[source]¶

Run preflight tool verification against an HTTP MCP endpoint.

Parameters:

endpoint (str)
required_tools (Iterable[str])
timeout (timedelta)

Return type:

None

ralph.mcp.protocol.startup.preflight_mcp_server_tools(endpoint, required_tools, timeout)[source]¶

Ensure the MCP server reports every tool that Ralph exposes.

Parameters:

endpoint (str)
required_tools (Iterable[str])
timeout (timedelta)

Return type:

None

ralph.mcp.protocol.startup.read_jsonrpc_response(reader)[source]¶

Read and parse a Content-Length-framed JSON-RPC response from a stream.

Parameters:: reader (io.BufferedReader)
Return type:: JsonRpcResponse

ralph.mcp.protocol.startup.write_jsonrpc_request(sock, value)[source]¶

Serialise and send a JSON-RPC message with a Content-Length header.

Parameters:

sock (socket)
value (dict[str, object])

Return type:

None

ralph.mcp.protocol.transport¶

MCP transport layer.

Provides transport abstractions for MCP communication. Supports stdio and HTTP/SSE connections to MCP clients and servers.

class ralph.mcp.protocol.transport.MCPMessage(method, params=None, msg_id=None, error=None)[source]¶

Bases: object

Represents an MCP message.

Parameters:

method (str)
params (dict[str, object] | None)
msg_id (str | int | None)
error (dict[str, object] | None)

ralph.mcp.protocol.transport.MCPTransport¶: alias of StdioTransport

class ralph.mcp.protocol.transport.StdioTransport(command, cwd=None, *, process_factory=None, thread_factory=None)[source]¶

Bases: object

MCP transport over stdio.

Communicates with an MCP server process via stdin/stdout. Each line is a JSON-RPC message.

Parameters:

command (list[str])
cwd (str | None)
process_factory (Callable[[list[str], str | None], ProcessLike] | None)
thread_factory (Callable[[Callable[[], None], bool], ThreadLike] | None)

async close()[source]¶

Close the transport.

Return type:: None

async recv()[source]¶

Receive messages as an async iterator.

Return type:: AsyncIterator[MCPMessage]

async send(message)[source]¶

Send a message to the MCP server.

Parameters:: message (MCPMessage)
Return type:: None

start()[source]¶

Start the MCP server process.

Return type:: None

exception ralph.mcp.protocol.transport.TransportError[source]¶

Bases: Exception

Raised when transport operations fail.

ralph.mcp.server¶

Standalone MCP server exports.

This package separates standalone server startup/shutdown helpers from the rest of the bridge implementation so callers can either launch an in-process session bridge or run the dedicated ralph-mcp HTTP runtime.

ralph.mcp.server.factory¶

Protocol and handle types for the MCP server factory abstraction.

class ralph.mcp.server.factory.McpServerFactory(*args, **kwargs)[source]¶

Bases: Protocol

Protocol that every MCP server factory implementation must satisfy.

class ralph.mcp.server.factory.McpServerHandle(endpoint, pid, shutdown)[source]¶

Bases: object

Return value from McpServerFactory.build carrying endpoint, PID, and shutdown hook.

Parameters:

endpoint (str)
pid (int)
shutdown (Callable[[], None])

ralph.mcp.server.factory_impl¶

Concrete MCP server factory that allocates dynamically bound localhost endpoints.

DynamicBindingMcpServerFactory is the production implementation of McpServerFactory. It reserves a unique TCP port per worker session, starts an MCP server subprocess via lifecycle.start_mcp_server, and returns a McpServerHandle that callers can use to reach the server or shut it down.

class ralph.mcp.server.factory_impl.DynamicBindingMcpServerFactory(workspace, *, reserve_port=None, start_server=<function start_mcp_server>, lifecycle_deps=None)[source]¶

Bases: McpServerFactory

Build MCP server handles with dynamically allocated localhost endpoints.

Parameters:

workspace (WorkspaceLike)
reserve_port (Callable[[], int] | None)
start_server (StartServer)
lifecycle_deps (lifecycle.LifecycleDeps | None)

ralph.mcp.server.lifecycle¶

MCP server lifecycle helpers using a standalone localhost HTTP process.

class ralph.mcp.server.lifecycle.LifecycleDeps(reserve_port, create_session_file, subprocess_env, spawn_process, preflight, preflight_timeout, probe=None, probe_timeout=None)[source]¶

Bases: object

Injectable dependencies for MCP server lifecycle management.

Parameters:

reserve_port (Callable[[], int])
create_session_file (Callable[[Path, SessionLike], Path])
subprocess_env (Callable[[Path], dict[str, str]])
spawn_process (SpawnProcess)
preflight (PreflightFn)
preflight_timeout (Callable[[], timedelta])
probe (Callable[[str, timedelta], None] | None)
probe_timeout (Callable[[], timedelta] | None)

class ralph.mcp.server.lifecycle.McpRestartPolicy(max_restarts=1000)[source]¶

Bases: object

Bounded restart policy for the MCP server bridge.

Parameters:: max_restarts (int)

exception ralph.mcp.server.lifecycle.McpServerError(message, *, restart_count)[source]¶

Bases: Exception

Raised when the MCP server fails and the restart budget is exhausted.

Parameters:

message (str)
restart_count (int)

Return type:

None

class ralph.mcp.server.lifecycle.McpServerExtras(phase=None, extra_env=None, restart_policy=None)[source]¶

Bases: object

Optional runtime extras for start_mcp_server.

Parameters:

phase (str | None)
extra_env (dict[str, str] | None)
restart_policy (McpRestartPolicy | None)

class ralph.mcp.server.lifecycle.ProcessLike(*args, **kwargs)[source]¶

Bases: Protocol

Subset of ManagedProcess API required by the MCP server lifecycle.

class ralph.mcp.server.lifecycle.RestartAwareMcpBridge(inner, *, restart_fn, restart_policy, probe_fn=None, probe_timeout_fn=None)[source]¶

Bases: object

SessionBridgeLike wrapper that auto-restarts the MCP server on crash.

Bounded restart budget prevents unbounded retry loops. All process spawning continues to flow through ProcessManager via the injected LifecycleDeps so ProcessManager remains the single process authority.

The endpoint URI is stable for the full bridge lifetime: the same host/port is reused on every restart so agents never see a changed MCP_ENDPOINT_ENV. Thread-safe: a lock guards all inner-process mutations so the background McpSupervisor can safely call check_health_and_restart_if_needed() while the main thread is executing agent output streaming.

Parameters:

inner (StandaloneMcpProcess)
restart_fn (Callable[[], StandaloneMcpProcess])
restart_policy (McpRestartPolicy)
probe_fn (Callable[[str, timedelta], None] | None)
probe_timeout_fn (Callable[[], timedelta] | None)

check_health_and_restart_if_needed()[source]¶

Check if MCP server is alive and responsive; restart if not.

Treats the bridge as unhealthy when either (a) the subprocess has exited or (b) the subprocess is alive but the responsiveness probe times out or fails. On an unhealthy result the stale process is terminated, a new one is spawned via restart_fn (which reruns full preflight), and the bounded restart counter is incremented.

Returns True when a restart was performed. Raises McpServerError when the restart budget is exhausted. Thread-safe: may be called from a background McpSupervisor thread.

Return type:: bool

class ralph.mcp.server.lifecycle.SessionBridgeLike(*args, **kwargs)[source]¶

Bases: Protocol

Protocol describing the session bridge interface used here.

agent_endpoint_uri()[source]¶

Return the agent-facing endpoint URI.

Return type:: str

endpoint_uri()[source]¶

Return the raw endpoint URI used for transport-level preflight.

Return type:: str

shutdown()[source]¶

Shut down the bridge.

Return type:: None

start()[source]¶

Start accepting MCP connections.

Return type:: None

class ralph.mcp.server.lifecycle.SpawnProcess(*args, **kwargs)[source]¶

Bases: Protocol

Callable that spawns the MCP server subprocess.

The phase keyword argument, when set, is used to label the process phase:<phase>:mcp-server so it is reaped by the phase-scope cleanup.

class ralph.mcp.server.lifecycle.StandaloneMcpProcess(endpoint, process, session_file)[source]¶

Bases: object

A running standalone MCP HTTP server process with its endpoint and session file.

Parameters:

endpoint (str)
process (ProcessLike)
session_file (Path)

ralph.mcp.server.lifecycle.check_mcp_bridge_health(bridge)[source]¶

Perform a health check on the MCP bridge, restarting if it crashed.

Only has an effect when bridge is a RestartAwareMcpBridge. Raises McpServerError when the restart budget is exhausted.

Parameters:: bridge (SessionBridgeLike)
Return type:: None

ralph.mcp.server.lifecycle.session_payload_json(session)[source]¶

Serialize the session metadata to a compact JSON string for MCP handshake.

Parameters:: session (ralph.mcp.protocol.startup.SessionLike)
Return type:: str

ralph.mcp.server.lifecycle.shutdown_mcp_server(bridge)[source]¶

Shutdown MCP server process.

Parameters:: bridge (SessionBridgeLike)
Return type:: None

ralph.mcp.server.lifecycle.start_mcp_server(session, workspace, *, upstream_registry=None, deps=None, extras=None)[source]¶

Start a standalone Ralph MCP HTTP subprocess and verify tool reachability.

Returns a RestartAwareMcpBridge that can auto-restart the server on crash up to the extras.restart_policy budget (default: 1000 restarts).

Parameters:

session (SessionLike)
workspace (WorkspaceLike)
upstream_registry (UpstreamRegistry | None)
deps (LifecycleDeps | None)
extras (McpServerExtras | None)

Return type:

RestartAwareMcpBridge

ralph.mcp.server.runtime¶

ralph.mcp.server.runtime_session¶

Session implementations for the Ralph MCP server.

Provides FileBackedSession (backed by a JSON file written by the parent Ralph process) and session_from_env (reads session state from environment variables).

class ralph.mcp.server.runtime_session.FileBackedSession(path, *, loader=None, session_id_factory=None, run_id_factory=None, env_getter=None)[source]¶

Bases: object

Session view backed by a JSON file updated by the parent Ralph process.

Parameters:

path (Path)
loader (Callable[[Path], dict[str, object]] | None)
session_id_factory (Callable[[], str] | None)
run_id_factory (Callable[[], str] | None)
env_getter (Callable[[str], str | None] | None)

property worker_artifact_dir: Path | None¶

Return worker artifact dir from environment variable.

For parallel workers, the parent process sets WORKER_ARTIFACT_DIR in the subprocess environment. This property reads that value so that artifact submission can route to the correct per-worker namespace.

ralph.mcp.server.runtime_session.session_from_env(env=None, *, session_id_factory=None, run_id_factory=None)[source]¶

Load optional session metadata from the environment.

Parameters:

env (Mapping[str, str] | None)
session_id_factory (Callable[[], str] | None)
run_id_factory (Callable[[], str] | None)

Return type:

AgentSession | None

ralph.mcp.server.main¶

ralph.mcp.multimodal¶

Ralph multimodal platform package.

Provides the shared contract for multimodal artifacts, provider/model capability detection, resource URI handling, session-scoped manifests, and failure taxonomy. All runtime layers that need multimodal behavior must derive their decisions from this package rather than duplicating provider or format knowledge.

ralph.mcp.multimodal.artifacts¶

Normalized multimodal artifact types for the MCP surface.

Defines the resource_reference content block shape that represents media artifacts that cannot be delivered inline (PDFs, audio, video, large images), as well as the modality class constants used across the multimodal platform.

class ralph.mcp.multimodal.artifacts.AudioContent(uri, mime_type, title, type='audio', delivery='typed_block')[source]¶

Bases: object

Typed audio content block referencing a manifest artifact.

Parameters:

uri (str)
mime_type (str)
title (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

class ralph.mcp.multimodal.artifacts.DocumentContent(uri, mime_type, title, type='document', delivery='typed_block')[source]¶

Bases: object

Typed document content block referencing a manifest artifact.

Parameters:

uri (str)
mime_type (str)
title (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

class ralph.mcp.multimodal.artifacts.ImageContent(data, mime_type, type='image', delivery='inline_image')[source]¶

Bases: object

Inline image content block delivered as base64-encoded bytes.

Parameters:

data (str)
mime_type (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

class ralph.mcp.multimodal.artifacts.PdfContent(uri, mime_type, title, type='pdf', delivery='typed_block')[source]¶

Bases: object

Typed PDF content block referencing a manifest artifact.

Parameters:

uri (str)
mime_type (str)
title (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

class ralph.mcp.multimodal.artifacts.ResourceReferenceContent(uri, mime_type, title, modality, type='resource_reference', delivery='resource_reference')[source]¶

Bases: object

Content block representing a media artifact via resource reference.

The delivery field distinguishes two cases:

'resource_reference_replay': a Ralph-owned ralph://media/... artifact stored in the session manifest. The agent calls read_media with the URI to retrieve or replay the artifact. Always pass delivery=DeliveryMode.RESOURCE_REFERENCE_REPLAY explicitly when constructing these blocks.
'resource_reference' (default): a URI-preserving upstream reference. The URI points to an external resource, not a Ralph-owned artifact. Used when an upstream MCP tool returns a URI-backed media block.

Parameters:

uri (str)
mime_type (str)
title (str)
modality (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

class ralph.mcp.multimodal.artifacts.VideoContent(uri, mime_type, title, type='video', delivery='typed_block')[source]¶

Bases: object

Typed video content block referencing a manifest artifact.

Parameters:

uri (str)
mime_type (str)
title (str)
type (str)
delivery (str)

to_dict()[source]¶

Serialize to MCP-compatible content block dictionary.

Return type:: dict[str, object]

ralph.mcp.multimodal.artifacts.infer_modality_and_mime(extension)[source]¶

Return (modality, mime_type) for a file extension, or None if unknown.

Parameters:: extension (str)
Return type:: tuple[str, str] | None

ralph.mcp.multimodal.capabilities¶

Multimodal capability detection and delivery policy.

This module is the single source of truth for provider/model identity, capability detection, and delivery policy decisions. All runtime layers that need to determine whether a modality can be delivered must derive their answer from this module rather than re-declaring provider knowledge elsewhere.

class ralph.mcp.multimodal.capabilities.CapabilityVerdict(modality, delivery, provider, model_id=None, reason='', block_type=None)[source]¶

Bases: object

Result of checking whether a modality/delivery mode is supported.

Parameters:

modality (str)
delivery (DeliveryMode)
provider (str)
model_id (str | None)
reason (str)
block_type (str | None)

is_inline()[source]¶

Return True if inline image delivery is used.

Return type:: bool

is_resource_reference()[source]¶

Return True if resource-reference replay delivery will be used.

Return type:: bool

is_supported()[source]¶

Return True if the modality has any supported delivery mode.

Return type:: bool

is_typed_block()[source]¶

Return True if typed block delivery will be used.

Return type:: bool

class ralph.mcp.multimodal.capabilities.DeliveryMode(*values)[source]¶

Bases: StrEnum

How a multimodal artifact will be delivered to the model.

class ralph.mcp.multimodal.capabilities.MultimodalModelIdentity(provider, model_id=None, transport=None)[source]¶

Bases: object

Identifies the provider and model for capability detection.

Parameters:

provider (str)
model_id (str | None)
transport (str | None)

is_known()[source]¶

Return True if the provider identity is resolved (not ‘unknown’).

Return type:: bool

class ralph.mcp.multimodal.capabilities.ResolvedCapabilityProfile(identity, verdicts)[source]¶

Bases: object

Pre-computed capability verdicts for a resolved model identity.

This is the runtime-owned contract for multimodal delivery decisions. Downstream layers consume this profile from the session rather than re-calling get_delivery_mode() at each use site.

Parameters:

identity (MultimodalModelIdentity)
verdicts (dict[str, CapabilityVerdict])

to_payload()[source]¶

Serialize to a JSON-compatible dict for session payload persistence.

Return type:: dict[str, object]

verdict_for(modality)[source]¶

Return the pre-computed verdict, or compute fresh for unlisted modalities.

Parameters:: modality (str)
Return type:: CapabilityVerdict

ralph.mcp.multimodal.capabilities.get_delivery_mode(identity, modality)[source]¶

Determine how to deliver a modality for the given model identity.

Returns a CapabilityVerdict indicating the delivery mode:

INLINE_IMAGE: provider accepts inline base64 image data.
TYPED_BLOCK: provider accepts a named typed block (pdf, document, audio, video).
RESOURCE_REFERENCE_REPLAY: unknown provider; multimodal surface stays visible via resource reference replay handle.
UNSUPPORTED: provider cannot accept this modality via Ralph’s managed path.

Unknown providers default to RESOURCE_REFERENCE_REPLAY (safe, keeps multimodal surface available without false typed-delivery promises).

Parameters:

identity (MultimodalModelIdentity)
modality (str)

Return type:

CapabilityVerdict

ralph.mcp.multimodal.capabilities.profile_from_payload(raw)[source]¶

Rehydrate a ResolvedCapabilityProfile from a serialized session payload dict.

Parameters:: raw (dict[str, object])
Return type:: ResolvedCapabilityProfile

ralph.mcp.multimodal.capabilities.resolve_capability_profile(identity)[source]¶

Build a pre-computed capability profile for all supported modalities.

Parameters:: identity (MultimodalModelIdentity)
Return type:: ResolvedCapabilityProfile

ralph.mcp.multimodal.errors¶

Shared multimodal failure taxonomy for Ralph’s managed MCP runtime path.

All code that needs to emit or classify a multimodal failure must use these types rather than constructing ad hoc error strings. This keeps failure messages consistent and machine-inspectable across capability detection, tool handlers, upstream normalization, and invoke-time checks.

class ralph.mcp.multimodal.errors.MultimodalFailure(kind, message, modality=None, provider=None, model_id=None)[source]¶

Bases: object

A structured description of why a multimodal operation could not complete.

Parameters:

kind (MultimodalFailureKind)
message (str)
modality (str | None)
provider (str | None)
model_id (str | None)

user_message()[source]¶

Return a human-readable failure message suitable for tool output.

Return type:: str

class ralph.mcp.multimodal.errors.MultimodalFailureKind(*values)[source]¶

Bases: StrEnum

Enumerated reasons why a multimodal operation failed.

ralph.mcp.multimodal.resources¶

URI builder/parser and session-scoped manifest for ralph://media resources.

The manifest tracks every resource_reference artifact emitted during a session so they can be listed via resources/list and retrieved via resources/read.

class ralph.mcp.multimodal.resources.ManifestEntry(artifact_id, uri, mime_type, title, modality, identity_key='', cache_path='', source_path='', source_uri='', _raw_bytes=None, _byte_loader=None)[source]¶

Bases: object

An entry in the session-scoped multimodal manifest.

Parameters:

artifact_id (str)
uri (str)
mime_type (str)
title (str)
modality (str)
identity_key (str)
cache_path (str)
source_path (str)
source_uri (str)
_raw_bytes (bytes | None)
_byte_loader (Callable[[], bytes | None] | None)

load_bytes()[source]¶

Return artifact bytes from memory or a backing replay source.

Return type:: bytes | None

property raw_bytes: bytes¶: Return artifact bytes, rehydrating from the loader when needed.

resource_list_entry()[source]¶

Return the entry shape for a resources/list response.

Return type:: dict[str, object]

set_replay_source(*, cache_path='', source_path='', source_uri='', byte_loader=None, retain_raw_bytes=False)[source]¶

Attach a durable replay source and optionally release in-memory bytes.

Parameters:

cache_path (str)
source_path (str)
source_uri (str)
byte_loader (Callable[[], bytes | None] | None)
retain_raw_bytes (bool)

Return type:

None

class ralph.mcp.multimodal.resources.MediaEntryExtras(cache_path='', source_path='', source_uri='', identity_key='', byte_loader=None)[source]¶

Bases: object

Optional extras when adding a media artifact to the manifest.

Parameters:

cache_path (str)
source_path (str)
source_uri (str)
identity_key (str)
byte_loader (ByteLoader | None)

class ralph.mcp.multimodal.resources.MediaManifest(_entries=<factory>, _identity_index=<factory>)[source]¶

Bases: object

Session-scoped manifest of all multimodal resource references.

Parameters:

_entries (dict[str, ManifestEntry])
_identity_index (dict[str, str])

add(*, title, mime_type, modality, raw_bytes, extras=None)[source]¶

Add or replace an artifact and return its manifest entry.

Parameters:

title (str)
mime_type (str)
modality (str)
raw_bytes (bytes)
extras (MediaEntryExtras | None)

Return type:

ManifestEntry

get(artifact_id)[source]¶

Retrieve a manifest entry by artifact_id, or None if not found.

Parameters:: artifact_id (str)
Return type:: ManifestEntry | None

is_empty()[source]¶

Return True if no artifacts have been stored.

Return type:: bool

list_entries()[source]¶

Return all manifest entries in insertion order.

Return type:: list[ManifestEntry]

class ralph.mcp.multimodal.resources.MediaSource(source_path='', source_uri='', raw_bytes=None)[source]¶

Bases: object

Source data for a media artifact (at most one field is set).

Parameters:

source_path (str)
source_uri (str)
raw_bytes (bytes | None)

ralph.mcp.multimodal.resources.build_media_identity(*, modality, mime_type, title, source=None)[source]¶

Build a stable identity for deduping repeated live artifacts.

Parameters:

modality (str)
mime_type (str)
title (str)
source (MediaSource | None)

Return type:

str

ralph.mcp.multimodal.resources.build_media_uri(artifact_id)[source]¶

Build a ralph://media/{artifact_id} URI.

Parameters:: artifact_id (str)
Return type:: str

ralph.mcp.multimodal.resources.new_artifact_id()[source]¶

Generate a new random artifact UUID.

Return type:: str

ralph.mcp.multimodal.resources.parse_media_uri(uri)[source]¶

Parse a ralph://media/{artifact_id} URI and return artifact_id, or None.

Parameters:: uri (str)
Return type:: str | None

ralph.mcp.effective_session_mcp_plan¶

Canonical effective MCP inventory for one agent session.

class ralph.mcp.effective_session_mcp_plan.EffectiveSessionMcpPlan(custom_servers, agent_upstream_servers, effective_servers, provider_visible_server_names=('ralph',))[source]¶

Bases: object

Canonical effective MCP inventory for one agent session.

Parameters:

custom_servers (tuple[UpstreamMcpServer, ...])
agent_upstream_servers (tuple[UpstreamMcpServer, ...])
effective_servers (tuple[UpstreamMcpServer, ...])
provider_visible_server_names (tuple[str, ...])

ralph.mcp.session_plan¶

Central runtime planner for per-session MCP availability.

This module is the single runtime source of truth for what MCP capabilities a new agent session should receive and what upstream MCP environment must be injected into the Ralph MCP subprocess for that session.

class ralph.mcp.session_plan.EffectiveSessionMcpPlan(custom_servers, agent_upstream_servers, effective_servers, provider_visible_server_names=('ralph',))[source]¶

Bases: object

Canonical effective MCP inventory for one agent session.

Parameters:

custom_servers (tuple[UpstreamMcpServer, ...])
agent_upstream_servers (tuple[UpstreamMcpServer, ...])
effective_servers (tuple[UpstreamMcpServer, ...])
provider_visible_server_names (tuple[str, ...])

class ralph.mcp.session_plan.SessionMcpPlan(capabilities, server_env=None, model_identity=MultimodalModelIdentity(provider='unknown', model_id=None, transport=None), capability_profile=None)[source]¶

Bases: object

Resolved MCP plan capturing capability grants and server environment for a session.

Parameters:

capabilities (frozenset[str])
server_env (dict[str, str] | None)
model_identity (MultimodalModelIdentity)
capability_profile (ResolvedCapabilityProfile | None)

class ralph.mcp.session_plan.SessionModelOpts(model_identity=None, model_flag=None)[source]¶

Bases: object

Optional model resolution parameters for build_session_mcp_plan.

Parameters:

model_identity (MultimodalModelIdentity | None)
model_flag (str | None)

ralph.mcp.session_plan.build_session_mcp_plan(*, transport, drain, workspace_path, agents_policy=None, model_opts=None, model_flag=None)[source]¶

Build the runtime MCP plan for a new agent session.

Identity resolution precedence: 1. model_identity (explicit, if provided) 2. model_flag resolved via resolve_model_identity(transport, model_flag) 3. UNKNOWN_IDENTITY fallback

Parameters:

transport (AgentTransport | None)
drain (str)
workspace_path (Path | None)
agents_policy (AgentsPolicy | None)
model_opts (SessionModelOpts | None)
model_flag (str | None)

Return type:

SessionMcpPlan

ralph.mcp.session_plan.effective_session_mcp_plan_from_servers(custom_servers, *, agent_upstream_servers=(), provider_visible_server_names=('ralph',))[source]¶

Build the canonical effective session MCP inventory from preloaded servers.

Parameters:

custom_servers (tuple[UpstreamMcpServer, ...])
agent_upstream_servers (tuple[UpstreamMcpServer, ...])
provider_visible_server_names (tuple[str, ...])

Return type:

EffectiveSessionMcpPlan

ralph.mcp.session_plan.resolve_effective_session_mcp_plan(workspace_path, *, agent_upstream_servers=(), provider_visible_server_names=('ralph',))[source]¶

Return the canonical effective MCP inventory for a session.

provider_visible_server_names captures the direct provider-visible MCP entries (typically just ralph), while effective_servers captures the merged custom + agent-native upstream server set that Ralph will proxy.

Parameters:

workspace_path (Path | None)
agent_upstream_servers (tuple[UpstreamMcpServer, ...])
provider_visible_server_names (tuple[str, ...])

Return type:

EffectiveSessionMcpPlan

ralph.mcp.session_plan.resolve_model_identity(transport, model_flag=None)[source]¶

Resolve multimodal model identity from agent transport and model flag.

Returns UNKNOWN_IDENTITY when the provider cannot be determined. For OpenCode transport, attempts a catalog lookup to determine the provider. On catalog failure or unmapped model, returns an unknown-provider identity that still carries model_id and transport so delivery falls back safely.

Parameters:

transport (AgentTransport | None)
model_flag (str | None)

Return type:

MultimodalModelIdentity

ralph.mcp.tools¶

MCP tool implementations Ralph exposes to agents.

This sub-package contains the handlers for every tool the Ralph MCP server advertises to connected AI agents (read_file, write_file, git_status, exec, submit_artifact, etc.). Ralph is the MCP server here.

ralph.mcp.tools.artifact¶

MCP artifact submission handlers.

class ralph.mcp.tools.artifact.ArtifactHandlerDeps(backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>, now_iso=<function _noop_now_iso>, history_enabled=False)[source]¶

Bases: object

Injectable dependencies for artifact handler operations.

Parameters:

backend (FileBackend)
now_iso (Callable[[], str])
history_enabled (bool)

class ralph.mcp.tools.artifact.SubmitOp(run, undo)[source]¶

Bases: object

An ordered submit step paired with its rollback action.

Parameters:

run (Callable[[], object])
undo (Callable[[], None])

ralph.mcp.tools.artifact.execute_ops_with_rollback(ops)[source]¶

Execute a sequence of ops; on failure roll back all completed ops in reverse.

Parameters:: ops (list[SubmitOp])
Return type:: None

ralph.mcp.tools.artifact.handle_discard_plan_draft(session, workspace, params, *, deps=None)[source]¶

Delete the on-disk plan draft so the agent can start over.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.artifact.handle_finalize_plan(session, workspace, params, *, deps=None)[source]¶

Validate the staged draft as a whole plan and write plan.json.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.artifact.handle_get_plan_draft(session, workspace, params, *, deps=None)[source]¶

Return the current plan draft so an agent can resume after a restart.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.artifact.handle_submit_artifact(session, workspace, params, *, deps=None)[source]¶

Validate and persist an artifact submitted by an MCP agent.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.artifact.handle_submit_plan_section(session, workspace, params, *, deps=None)[source]¶

Validate a single plan section and merge it into the on-disk draft.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.artifact.prepare_artifact_submission(params, *, session_drain=None, base_path=None, backend=<ralph.mcp.artifacts._path_file_backend.PathFileBackend object>)[source]¶

Validate and canonicalize artifact submission params, returning (artifact_type, params).

Parameters:

params (dict[str, object])
session_drain (str | None)
base_path (Path | None)
backend (FileBackend)

Return type:

tuple[str, dict[str, object]]

ralph.mcp.tools.artifact.submit_ops_for_artifact(artifact_type, workspace_root, artifact_dir, parsed_content, *, deps)[source]¶

Return the ordered (op, undo) pairs for a complete artifact submit.

Parameters:

artifact_type (str)
workspace_root (Path)
artifact_dir (Path)
parsed_content (dict[str, object])
deps (ArtifactHandlerDeps)

Return type:

list[SubmitOp]

ralph.mcp.tools.plan_draft_edit¶

Precise MCP handlers for plan draft step edits.

ralph.mcp.tools.plan_draft_edit.handle_insert_plan_step(session, workspace, params, *, deps=None)[source]¶

Insert a single plan step and reindex the draft deterministically.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.plan_draft_edit.handle_remove_plan_step(session, workspace, params, *, deps=None)[source]¶

Remove a single plan step and reindex the draft deterministically.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.plan_draft_edit.handle_replace_plan_step(session, workspace, params, *, deps=None)[source]¶

Replace a single plan step and reindex the draft deterministically.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
deps (ArtifactHandlerDeps | None)

Return type:

ralph.mcp.tools.bridge¶

MCP tool registry and handler dispatch.

This module ports the Rust mcp_server::tool_bridge registry layer into Python. It owns tool metadata registration, duplicate protection, lookup, and dispatch. The default registry builder mirrors the Rust bridge by registering lazy handler wrappers for the Ralph MCP tool modules.

class ralph.mcp.tools.bridge.LazyToolHandler(*, module_name, handler_name, session, workspace, extra_kwargs=None)[source]¶

Bases: object

Lazy wrapper that imports the real MCP tool handler on demand.

Parameters:

module_name (str)
handler_name (str)
session (object)
workspace (object)
extra_kwargs (dict[str, object] | None)

class ralph.mcp.tools.bridge.RegisteredTool(metadata, handler)[source]¶

Bases: object

A registered tool and its executable handler.

Parameters:

metadata (ToolMetadata)
handler (RegistrationHandler)

class ralph.mcp.tools.bridge.RegistrationHandler(*args, **kwargs)[source]¶

Bases: Protocol

Callable protocol for MCP tool handler functions registered in the tool bridge.

class ralph.mcp.tools.bridge.ToolBridge(session=None)[source]¶

Bases: object

Registry for MCP tools and dispatcher for tool invocations.

Parameters:: session (object | None)

dispatch(name, params=None, *, host_session=None, workspace=None)[source]¶

Dispatch a tool invocation to its registered handler.

Parameters:

name (str)
params (JsonObject | None)
host_session (object | None)
workspace (object | None)

Return type:

object

get(name)[source]¶

Return a registered tool or raise if it does not exist.

Parameters:: name (str)
Return type:: RegisteredTool

has_tool(name)[source]¶

Return whether a tool is registered.

Parameters:: name (str)
Return type:: bool

list_definitions()[source]¶

Return public tool definitions in registration order.

Return type:: list[ToolDefinition]

list_metadata()[source]¶

Return tool metadata in registration order.

Return type:: list[ToolMetadata]

register(metadata, handler)[source]¶

Parameters:

metadata (ToolMetadata)
handler (RegistrationHandler)

Return type:

None

register_spec(spec, *, session, workspace)[source]¶

Parameters:

spec (ToolSpec)
session (object)
workspace (object)

Return type:

None

set_client_capabilities(capabilities)[source]¶

Set the client declared capabilities from MCP initialize handshake.

Parameters:: capabilities (set[str] | None)
Return type:: None

exception ralph.mcp.tools.bridge.ToolBridgeError[source]¶

Bases: Exception

Base exception for tool bridge failures.

class ralph.mcp.tools.bridge.ToolDefinition(name, description, input_schema)[source]¶

Bases: object

Public MCP-facing tool definition.

Parameters:

name (str)
description (str)
input_schema (JsonObject)

exception ralph.mcp.tools.bridge.ToolDispatchError[source]¶

Bases: ToolBridgeError

Raised when tool dispatch fails.

class ralph.mcp.tools.bridge.ToolMetadata(definition, required_capability, is_mutating=None, is_multimodal=False)[source]¶

Bases: object

Internal tool registration metadata.

Parameters:

definition (ToolDefinition)
required_capability (str)
is_mutating (bool | None)
is_multimodal (bool)

exception ralph.mcp.tools.bridge.ToolRegistrationError[source]¶

Bases: ToolBridgeError

Raised when tool registration is invalid.

class ralph.mcp.tools.bridge.ToolSpec(metadata, module_name, handler_name)[source]¶

Bases: object

Full registration spec, including lazy import target.

Parameters:

metadata (ToolMetadata)
module_name (str)
handler_name (str)

class ralph.mcp.tools.bridge.UpstreamProxyHandler(alias, upstream_registry)[source]¶

Bases: object

Proxy handler that forwards tool calls to an upstream MCP registry.

Parameters:

alias (str)
upstream_registry (UpstreamRegistry)

ralph.mcp.tools.bridge.build_ralph_tool_registry(session, workspace, *, upstream_registry=None, mcp_config=None)[source]¶

Build the default Ralph MCP tool registry.

Parameters:

session (object)
workspace (object)
upstream_registry (UpstreamRegistry | None)
mcp_config (McpConfig | None)

Return type:

ToolBridge

ralph.mcp.tools.bridge.tool_specs(mcp_config)[source]¶

Build the full ordered list of tool specifications for the MCP bridge.

Parameters:: mcp_config (McpConfig)
Return type:: tuple[ToolSpec, …]

ralph.mcp.tools.coordination¶

MCP tool call coordination handlers.

Ports the Rust coordination handlers that support progress reporting, completion declaration, workspace coordination, and environment reads.

exception ralph.mcp.tools.coordination.CapabilityDeniedError[source]¶

Bases: ToolError

Raised when a required session capability is not available.

class ralph.mcp.tools.coordination.CoordinationSessionLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimum session surface required by coordination handlers.

check_capability(capability)[source]¶

Return a policy outcome for the requested capability.

Parameters:: capability (str)
Return type:: object

exception ralph.mcp.tools.coordination.InvalidParamsError[source]¶

Bases: ToolError

Raised when tool parameters are missing or invalid.

class ralph.mcp.tools.coordination.ToolContent(type, text)[source]¶

Bases: object

Single text tool response content block.

Parameters:

type (str)
text (str)

classmethod text_content(text)[source]¶

Create a text content block.

Parameters:: text (str)
Return type:: ToolContent

to_dict()[source]¶

Serialize the content block to a dictionary.

Return type:: dict[str, str]

exception ralph.mcp.tools.coordination.ToolError[source]¶

Bases: Exception

Base error raised by MCP tool handlers.

class ralph.mcp.tools.coordination.ToolResult(content, is_error=None)[source]¶

Bases: object

Serializable MCP tool result.

Parameters:

content (list[ContentBlock])
is_error (bool | None)

to_dict()[source]¶

Serialize the result to an MCP-compatible dictionary.

Return type:: dict[str, object]

class ralph.mcp.tools.coordination.WorkspaceLike(*args, **kwargs)[source]¶

Bases: Protocol

Placeholder workspace protocol for handler parity.

absolute_path(path)[source]¶

Return an absolute workspace path for the provided relative path.

Parameters:: path (str)
Return type:: str

ralph.mcp.tools.coordination.format_coordination_text(action, session_id, timestamp, work_unit_id, payload)[source]¶

Format the coordination response text.

Parameters:

action (str)
session_id (str)
timestamp (int)
work_unit_id (str | None)
payload (object | None)

Return type:

str

ralph.mcp.tools.coordination.format_progress_text(status, note, timestamp)[source]¶

Build the progress report response text.

Parameters:

status (str)
note (str)
timestamp (int)

Return type:

str

ralph.mcp.tools.coordination.handle_coordinate(session, _workspace, params, *, now_fn=<function _timestamp>)[source]¶

Coordinate parallel worker activities.

Parameters:

session (CoordinationSessionLike)
_workspace (WorkspaceLike)
params (dict[str, object])
now_fn (Callable[[], int])

Return type:

ralph.mcp.tools.coordination.handle_declare_complete(session, workspace, params, *, now_fn=<function _timestamp>)[source]¶

Declare that the agent has completed its assigned task.

Parameters:

session (CoordinationSessionLike)
workspace (WorkspaceLike)
params (dict[str, object])
now_fn (Callable[[], int])

Return type:

ralph.mcp.tools.coordination.handle_read_env(session, _workspace, params, *, env=environ({'BUNDLER_ORIG_BUNDLER_SETUP': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_BUNDLER_VERSION': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_BUNDLE_BIN_PATH': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_BUNDLE_GEMFILE': '/home/mistlight/.openclaw/workspace/Ralph-Site/Gemfile', 'BUNDLER_ORIG_BUNDLE_LOCKFILE': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_GEM_HOME': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_GEM_PATH': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_MANPATH': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_PATH': '/home/mistlight/.rbenv/versions/4.0.1/bin:/usr/lib/rbenv/libexec:/home/mistlight/.rbenv/plugins/ruby-build/bin:/home/mistlight/.rbenv/shims:/home/mistlight/.rbenv/bin:/home/mistlight/.bun/bin:/home/mistlight/.cargo/bin:/usr/bin:/bin:/home/mistlight/.local/share/pnpm:/home/mistlight/.nvm/current/bin:/home/mistlight/.local/bin:/home/mistlight/.npm-global/bin:/home/mistlight/bin:/home/mistlight/.nix-profile/bin:/usr/local/bin', 'BUNDLER_ORIG_RB_USER_INSTALL': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_RUBYLIB': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_ORIG_RUBYOPT': 'BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL', 'BUNDLER_SETUP': '/home/mistlight/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.6/lib/bundler/setup', 'BUNDLER_VERSION': '4.0.6', 'BUNDLE_BIN_PATH': '/home/mistlight/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.6/exe/bundle', 'BUNDLE_GEMFILE': '/home/mistlight/.openclaw/workspace/Ralph-Site/Gemfile', 'BUNDLE_LOCKFILE': '/home/mistlight/.openclaw/workspace/Ralph-Site/Gemfile.lock', 'DBUS_SESSION_BUS_ADDRESS': 'unix:path=/run/user/1000/bus', 'GEM_HOME': '/home/mistlight/.openclaw/workspace/Ralph-Site/vendor/bundle/ruby/4.0.0', 'GEM_PATH': '', 'GPG_AGENT_INFO': '/run/user/1000/gnupg/S.gpg-agent:0:1', 'HOME': '/home/mistlight', 'INVOCATION_ID': '2b982bd64066424d965ccb02933c94d1', 'JOURNAL_STREAM': '9:427841637', 'LANG': 'en_US.UTF-8', 'LOGNAME': 'mistlight', 'MANAGERPID': '3209050', 'MEMORY_PRESSURE_WATCH': '/sys/fs/cgroup/user.slice/user-1000.slice/user@1000.service/app.slice/openclaw-gateway.service/memory.pressure', 'MEMORY_PRESSURE_WRITE': 'c29tZSAyMDAwMDAgMjAwMDAwMAA=', 'NODE_EXTRA_CA_CERTS': '/etc/ssl/certs/ca-certificates.crt', 'OLDPWD': '/home/mistlight/.openclaw/workspace', 'OPENCLAW_CLI': '1', 'OPENCLAW_GATEWAY_PORT': '18789', 'OPENCLAW_PATH_BOOTSTRAPPED': '1', 'OPENCLAW_SERVICE_KIND': 'gateway', 'OPENCLAW_SERVICE_MARKER': 'openclaw', 'OPENCLAW_SERVICE_VERSION': '2026.5.7', 'OPENCLAW_SHELL': 'exec', 'OPENCLAW_SYSTEMD_UNIT': 'openclaw-gateway.service', 'OPENCLAW_WINDOWS_TASK_NAME': 'OpenClaw Gateway', 'PATH': '/home/mistlight/.openclaw/workspace/Ralph-Site/tmp/docs_build/ralph-workflow/.venv/bin:/home/mistlight/.openclaw/workspace/Ralph-Site/vendor/bundle/ruby/4.0.0/bin:/home/mistlight/.rbenv/versions/4.0.1/bin:/usr/lib/rbenv/libexec:/home/mistlight/.rbenv/plugins/ruby-build/bin:/home/mistlight/.rbenv/shims:/home/mistlight/.rbenv/bin:/home/mistlight/.bun/bin:/home/mistlight/.cargo/bin:/usr/bin:/bin:/home/mistlight/.local/share/pnpm:/home/mistlight/.nvm/current/bin:/home/mistlight/.local/bin:/home/mistlight/.npm-global/bin:/home/mistlight/bin:/home/mistlight/.nix-profile/bin:/usr/local/bin', 'PWD': '/home/mistlight/.openclaw/workspace/Ralph-Site', 'PYTHONPATH': '/home/mistlight/.openclaw/workspace/Ralph-Site/tmp/docs_build/ralph-workflow', 'RALPH_SITE_RBENV_REEXEC': '1', 'RBENV_DIR': '/home/mistlight/.openclaw/workspace/Ralph-Site', 'RBENV_HOOK_PATH': '/home/mistlight/.rbenv/rbenv.d:/usr/lib/rbenv/rbenv.d:/usr/local/etc/rbenv.d:/etc/rbenv.d:/usr/lib/rbenv/hooks', 'RBENV_ROOT': '/home/mistlight/.rbenv', 'RBENV_VERSION': '4.0.1', 'RUBYLIB': '/home/mistlight/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.6/lib', 'RUBYOPT': '-r/home/mistlight/.rbenv/versions/4.0.1/lib/ruby/gems/4.0.0/gems/bundler-4.0.6/lib/bundler/setup', 'SHLVL': '0', 'SSH_AUTH_SOCK': '/run/user/1000/openssh_agent', 'SYSTEMD_EXEC_PID': '3966176', 'TMPDIR': '/tmp', 'USER': 'mistlight', 'UV': '/home/mistlight/.local/bin/uv', 'UV_RUN_RECURSION_DEPTH': '1', 'VIRTUAL_ENV': '/home/mistlight/.openclaw/workspace/Ralph-Site/tmp/docs_build/ralph-workflow/.venv', 'XDG_RUNTIME_DIR': '/run/user/1000', 'DOCUTILSCONFIG': '/home/mistlight/.openclaw/workspace/Ralph-Site/tmp/docs_build/ralph-workflow/docs/sphinx/docutils.conf'}))[source]¶

Read an environment variable by name.

Parameters:

session (CoordinationSessionLike)
_workspace (WorkspaceLike)
params (dict[str, object])
env (dict[str, str] | _Environ[str])

Return type:

ralph.mcp.tools.coordination.handle_report_progress(session, _workspace, params, *, now_fn=<function _timestamp>)[source]¶

Report agent progress to the Ralph pipeline.

Parameters:

session (CoordinationSessionLike)
_workspace (WorkspaceLike)
params (dict[str, object])
now_fn (Callable[[], int])

Return type:

ralph.mcp.tools.coordination.require_capability(session, capability, action)[source]¶

Require a capability, raising a capability-denied error when missing.

Parameters:

session (CoordinationSessionLike)
capability (str)
action (str)

Return type:

None

ralph.mcp.tools.exec¶

MCP exec tool handler.

Ports the Rust MCP exec tool so agents can execute bounded subprocesses from the workspace root after capability checks and blacklist filtering.

class ralph.mcp.tools.exec.ExecParams(command, args, timeout_ms)[source]¶

Bases: object

Parsed parameters for the MCP exec tool.

Parameters:

command (str)
args (list[str])
timeout_ms (int)

class ralph.mcp.tools.exec.ExecRunDeps(runner=None, cwd_provider=None)[source]¶

Bases: object

Injectable dependencies for exec tool command execution.

Parameters:

runner (CommandRunner | None)
cwd_provider (CwdProvider | None)

exception ralph.mcp.tools.exec.ExecutionError[source]¶

Bases: ToolError

Raised when the exec subprocess cannot be started or times out.

class ralph.mcp.tools.exec.WorkspaceWithRoot(*args, **kwargs)[source]¶

Bases: Protocol

Workspace surface required for command execution.

property root: Path¶: Return the absolute workspace root path.

ralph.mcp.tools.exec.apply_exec_policy(command, args)[source]¶

Apply command policy and raise if the command is denied.

Parameters:

command (str)
args (list[str])

Return type:

None

ralph.mcp.tools.exec.check_command(command, args)[source]¶

Return a denial reason when a command matches the blacklist policy.

Parameters:

command (str)
args (list[str])

Return type:

str | None

ralph.mcp.tools.exec.format_exec_result(command, args, output, timeout_ms)[source]¶

Format subprocess output to match the Rust tool response.

Parameters:

command (str)
args (list[str])
output (_CompletedProcessAdapter)
timeout_ms (int)

Return type:

str

ralph.mcp.tools.exec.handle_exec_command(session, workspace, params)[source]¶

Execute a bounded subprocess in the workspace root.

Parameters:

session (CoordinationSessionLike)
workspace (object)
params (Mapping[str, object])

Return type:

ralph.mcp.tools.exec.parse_exec_params(params)[source]¶

Parse and validate exec tool parameters.

Parameters:: params (Mapping[str, object])
Return type:: ExecParams

ralph.mcp.tools.exec.run_command(command, args, workspace, timeout_ms, deps=None)[source]¶

Execute a subprocess in the workspace root.

Parameters:

command (str)
args (list[str])
workspace (object)
timeout_ms (int)
deps (ExecRunDeps | None)

Return type:

_CompletedProcessAdapter

ralph.mcp.tools.git_read¶

MCP Git read tool handlers.

Ports the Rust MCP Git read tools so agents can inspect repository state through bounded read-only git commands from the workspace root.

exception ralph.mcp.tools.git_read.ExecutionError[source]¶

Bases: ToolError

Raised when a git subprocess cannot be started or fails.

class ralph.mcp.tools.git_read.GitDiffParams(args)[source]¶

Bases: object

Parsed parameters for the git diff tool.

Parameters:: args (list[str])

class ralph.mcp.tools.git_read.GitLogParams(count)[source]¶

Bases: object

Parsed parameters for the git log tool.

Parameters:: count (int)

class ralph.mcp.tools.git_read.GitShowParams(git_ref)[source]¶

Bases: object

Parsed parameters for the git show tool.

Parameters:: git_ref (str)

class ralph.mcp.tools.git_read.WorkspaceWithRoot(*args, **kwargs)[source]¶

Bases: Protocol

Workspace surface required for git command execution.

property root: Path¶: Return the absolute workspace root path.

ralph.mcp.tools.git_read.handle_git_diff(session, workspace, params)[source]¶

Read the git diff of the workspace.

Parameters:

session (CoordinationSessionLike)
workspace (object)
params (Mapping[str, object])

Return type:

ralph.mcp.tools.git_read.handle_git_log(session, workspace, params)[source]¶

Read the git commit log.

Parameters:

session (CoordinationSessionLike)
workspace (object)
params (Mapping[str, object])

Return type:

ralph.mcp.tools.git_read.handle_git_show(session, workspace, params)[source]¶

Show a git object by ref.

Parameters:

session (CoordinationSessionLike)
workspace (object)
params (Mapping[str, object])

Return type:

ralph.mcp.tools.git_read.handle_git_status(session, workspace, _params)[source]¶

Read the git status of the workspace.

Parameters:

session (CoordinationSessionLike)
workspace (object)
_params (Mapping[str, object])

Return type:

ralph.mcp.tools.git_read.parse_git_diff_params(params)[source]¶

Parse git diff params, keeping only string arguments.

Parameters:: params (Mapping[str, object])
Return type:: GitDiffParams

ralph.mcp.tools.git_read.parse_git_log_params(params)[source]¶

Parse git log params with the Rust default count.

Parameters:: params (Mapping[str, object])
Return type:: GitLogParams

ralph.mcp.tools.git_read.parse_git_show_params(params)[source]¶

Parse git show params.

Parameters:: params (Mapping[str, object])
Return type:: GitShowParams

ralph.mcp.tools.git_read.run_git_command(workspace, args, *, runner=None, cwd_provider=<bound method Path.cwd of <class 'pathlib.Path'>>)[source]¶

Execute git and require a successful exit status.

Parameters:

workspace (object)
args (list[str])
runner (GitRunner | None)
cwd_provider (CwdProvider)

Return type:

str

ralph.mcp.tools.git_read.run_git_command_lenient(workspace, args, *, runner=None, cwd_provider=<bound method Path.cwd of <class 'pathlib.Path'>>)[source]¶

Execute git and return combined stdout/stderr regardless of exit code.

Parameters:

workspace (object)
args (list[str])
runner (GitRunner | None)
cwd_provider (CwdProvider)

Return type:

str

ralph.mcp.tools.names¶

Canonical Ralph MCP tool naming helpers.

class ralph.mcp.tools.names.RalphToolName(*values)[source]¶

Bases: StrEnum

Canonical names for all Ralph MCP tools.

as_claude_alias(*, server_name='ralph')[source]¶

Return the Claude MCP tool alias in the form mcp__<server>__<tool>.

Parameters:: server_name (str)
Return type:: str

prompt_aliases(*, tool_name_prefix='')[source]¶

Return the full set of prompt-facing alias names for this tool.

Parameters:: tool_name_prefix (str)
Return type:: tuple[str, …]

prompt_reference(*, tool_name_prefix='')[source]¶

Return a human-readable reference string for prompts.

Parameters:: tool_name_prefix (str)
Return type:: str

with_prefix(*, tool_name_prefix='')[source]¶

Return the tool name with an optional prefix applied.

Parameters:: tool_name_prefix (str)
Return type:: str

ralph.mcp.tools.names.claude_tool_name(tool_name, *, server_name='ralph')[source]¶

Return the Claude MCP alias for a tool name (mcp__<server>__<tool>).

Parameters:

tool_name (str | RalphToolName)
server_name (str)

Return type:

str

ralph.mcp.tools.names.claude_tool_name_prefix(*, server_name='ralph')[source]¶

Return the mcp__<server>__ prefix string used by Claude for MCP tools.

Parameters:: server_name (str)
Return type:: str

ralph.mcp.tools.names.custom_proxy_tool_name(server_name, tool_name)[source]¶

Return the stable proxy alias for a Ralph custom MCP server tool.

Parameters:

server_name (str)
tool_name (str)

Return type:

str

ralph.mcp.tools.names.prefix_tool_name(tool_name, *, tool_name_prefix='')[source]¶

Return the tool name with an optional prefix applied.

Parameters:

tool_name (str | RalphToolName)
tool_name_prefix (str)

Return type:

str

ralph.mcp.tools.names.prefix_tool_names(tool_names, *, tool_name_prefix='')[source]¶

Apply the given prefix to each tool name in the sequence.

Parameters:

tool_names (Sequence[str | RalphToolName])
tool_name_prefix (str)

Return type:

list[str]

ralph.mcp.tools.names.proxied_mcp_tool_name(server_name, tool_name, *, origin)[source]¶

Return the stable proxy alias for a proxied MCP server tool.

Parameters:

server_name (str)
tool_name (str)
origin (str)

Return type:

str

ralph.mcp.tools.names.upstream_proxy_tool_name(server_name, tool_name)[source]¶

Return the stable proxy alias for an agent-native upstream MCP server tool.

Parameters:

server_name (str)
tool_name (str)

Return type:

str

ralph.mcp.tools.websearch¶

MCP tool handler for web search across pluggable backends.

Exposes handle_web_search, which dispatches a search query through the configured backend (and optional fallbacks) and returns a ToolResult. Backends are loaded lazily; the dispatch order is taken from WebSearchConfig.

ralph.mcp.tools.websearch.handle_web_search(session, _workspace, params, *, web_search_config=None)[source]¶

Dispatch a web search query through the configured backend and return results.

Parameters:

session (CoordinationSessionLike)
_workspace (Workspace)
params (dict[str, object])
web_search_config (WebSearchConfig | None)

Return type:

ralph.mcp.tools.webvisit¶

MCP tool handler for visit_url: fetch one URL and return readable text.

ralph.mcp.tools.webvisit.handle_visit_url(session, _workspace, params, *, web_visit_config=None)[source]¶

Fetch a URL and return readable extracted text.

Parameters:

session (CoordinationSessionLike)
_workspace (Workspace)
params (dict[str, object])
web_visit_config (WebVisitConfig | None)

Return type:

ralph.mcp.tools.workspace¶

Workspace tool handlers for MCP interactions.

Ports the Rust mcp_server::tool_workspace helpers into Python so MCP handlers can read, list, search, and write workspace files while enforcing session capabilities and edit area policies.

ralph.mcp.tools.workspace.handle_append_file(session, workspace, params)[source]¶

Append content to a workspace file.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_copy_file(session, workspace, params)[source]¶

Copy a workspace file or directory to a new location.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_create_directory(session, workspace, params)[source]¶

Create a directory (and parents) within the workspace.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_delete_path(session, workspace, params)[source]¶

Delete a workspace file or directory.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_directory_tree(session, workspace, params)[source]¶

Return a nested JSON directory tree for a workspace path.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_edit_file(session, workspace, params)[source]¶

Apply structured oldText/newText replacements to a workspace file.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_grep_files(session, workspace, params)[source]¶

Search file contents for a pattern and return line-level matches.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_list_allowed_roots(session, workspace, params)[source]¶

Return the list of workspace paths the session is permitted to access.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_list_directory(session, workspace, params)[source]¶

List entries in a workspace directory, optionally recursive.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_list_directory_recursive(session, workspace, params)[source]¶

Return a flat listing of all entries under a workspace directory.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_move_file(session, workspace, params)[source]¶

Move or rename a workspace file or directory.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_read_file(session, workspace, params)[source]¶

Read a UTF-8 file from the workspace.

Full-file reads (no partial params) return a plain text block for UTF-8 files at or below max_bytes (default 5_000_000). The JSON envelope only appears when truncated is True OR when an error occurs (binary_or_invalid_utf8).

Partial-read parameter groups (line_start/line_end, offset/limit, head, tail) are mutually exclusive; combining any two raises InvalidParams.

Optional param max_bytes overrides the default ceiling for full-file reads.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_read_image(session, workspace, params, *, max_inline_bytes=5242880)[source]¶

Read an image file and return it as a capability-aware content block.

Requires MediaRead capability. Validates that the file is a supported image format, then delegates to the shared workspace media handler for delivery decision (inline image, typed block, or explicit unsupported/error).

This is a compatibility alias over _handle_workspace_media that restricts inputs to image formats only while preserving the same truthful delivery contract as read_media.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])
max_inline_bytes (int)

Return type:

ralph.mcp.tools.workspace.handle_read_media(session, workspace, params, *, max_inline_bytes=5242880)[source]¶

Read a media file or replay a stored artifact handle.

Accepts either: - a workspace file path (e.g., screenshots/shot.png) - a ralph://media/{artifact_id} replay handle from a prior session

When given a replay handle, rehydrates the artifact from the live session manifest and returns the same typed block that was originally emitted. Invalid or unrecognised handles return an explicit structured failure.

For workspace paths, delivery mode is determined by the session’s model identity via the capability matrix: INLINE_IMAGE, TYPED_BLOCK, RESOURCE_REFERENCE_REPLAY, or UNSUPPORTED.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])
max_inline_bytes (int)

Return type:

ralph.mcp.tools.workspace.handle_read_multiple_files(session, workspace, params)[source]¶

Read multiple workspace files in one call and return per-file results.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_search_files(session, workspace, params)[source]¶

Search for files matching a glob pattern within a workspace directory.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_stat(session, workspace, params)[source]¶

Return file metadata (type, size, timestamps) for a workspace path.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

ralph.mcp.tools.workspace.handle_write_file(session, workspace, params)[source]¶

Write UTF-8 content to a workspace file, creating it if necessary.

Parameters:

session (CoordinationSessionLike)
workspace (Workspace)
params (dict[str, object])

Return type:

HttpUpstreamClient | StdioUpstreamClient

ralph.mcp.tools.workspace.is_policy_approved(outcome)[source]¶

Return True if the given policy outcome represents an approval decision.

Parameters:: outcome (object | None)
Return type:: bool

ralph.mcp.tools.workspace.match_glob(rel_path, pattern)[source]¶

Match a path against a glob pattern supporting , *, and ? segments.

Parameters:

rel_path (str)
pattern (str)

Return type:

bool

ralph.mcp.tools.workspace.persist_upstream_media_artifacts(result, session, workspace)[source]¶

Persist upstream embedded media artifacts to the durable cache and session index.

Called after normalize_upstream_content_blocks so that:

resource_reference_replay blocks (backed by ralph://media/… URIs stored in the session manifest) are written to the durable cache and session index, enabling cross-session replay of artifacts from upstream embedded-data blocks.
URI-backed resource_reference blocks (delivery=’resource_reference’) reference external URIs and cannot be replayed across sessions. These are synthesized as unsupported_runtime_seam entries so the failure is explicit at invoke time.

Parameters:

result (object)
session (object)
workspace (Workspace)

Return type:

None

ralph.mcp.tools.workspace.required_string_param(params, name)[source]¶

Return a required string parameter, raising if it is missing.

Parameters:

params (dict[str, object])
name (str)

Return type:

str

ralph.mcp.tools.capability_denied_error¶

Capability-denied MCP tool error.

exception ralph.mcp.tools.capability_denied_error.CapabilityDeniedError[source]¶

Bases: ToolError

Raised when a required session capability is not available.

ralph.mcp.tools.coordination_session_like¶

Protocol for coordination tool session access.

class ralph.mcp.tools.coordination_session_like.CoordinationSessionLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimum session surface required by coordination handlers.

check_capability(capability)[source]¶

Return a policy outcome for the requested capability.

Parameters:: capability (str)
Return type:: object

ralph.mcp.tools.invalid_params_error¶

Invalid MCP tool parameter error.

exception ralph.mcp.tools.invalid_params_error.InvalidParamsError[source]¶

Bases: ToolError

Raised when tool parameters are missing or invalid.

ralph.mcp.tools.tool_content¶

MCP tool text content block.

class ralph.mcp.tools.tool_content.ToolContent(type, text)[source]¶

Bases: object

Single text tool response content block.

Parameters:

type (str)
text (str)

classmethod text_content(text)[source]¶

Create a text content block.

Parameters:: text (str)
Return type:: ToolContent

to_dict()[source]¶

Serialize the content block to a dictionary.

Return type:: dict[str, str]

ralph.mcp.tools.tool_error¶

Base error raised by MCP tool handlers.

exception ralph.mcp.tools.tool_error.ToolError[source]¶

Bases: Exception

Base error raised by MCP tool handlers.

ralph.mcp.tools.tool_result¶

Serializable MCP tool result.

class ralph.mcp.tools.tool_result.ToolResult(content, is_error=None)[source]¶

Bases: object

Serializable MCP tool result.

Parameters:

content (list[ContentBlock])
is_error (bool | None)

to_dict()[source]¶

Serialize the result to an MCP-compatible dictionary.

Return type:: dict[str, object]

ralph.mcp.tools.workspace_like¶

Protocol for workspace access used by coordination tools.

class ralph.mcp.tools.workspace_like.WorkspaceLike(*args, **kwargs)[source]¶

Bases: Protocol

Placeholder workspace protocol for handler parity.

absolute_path(path)[source]¶

Return an absolute workspace path for the provided relative path.

Parameters:: path (str)
Return type:: str

ralph.mcp.transport¶

Public transport helpers for per-agent MCP wiring.

Grouped by agent: claude, codex, opencode, agy. Shared helpers (mcp.toml merging, env serialization) live in common.

ralph.mcp.transport.agy_mcp_config(endpoint)[source]¶

Return the AGY MCP JSON config string pointing to the given endpoint.

Parameters:: endpoint (str) – The MCP server HTTP endpoint URL.
Returns:: JSON string with mcpServers containing the Ralph entry with serverUrl key.
Return type:: str

ralph.mcp.transport.build_opencode_provider_config(existing, endpoint)[source]¶

Build a full OpenCode config JSON with Ralph MCP and return it with upstream servers.

Parameters:

existing (str | None)
endpoint (str)

Return type:

tuple[str, tuple[UpstreamMcpServer, …]]

ralph.mcp.transport.claude_mcp_config(endpoint, *, workspace_path=None)[source]¶

Return the Claude MCP JSON config string pointing to the given endpoint.

Parameters:

endpoint (str)
workspace_path (Path | None)

Return type:

str

ralph.mcp.transport.load_existing_agy_upstream_servers(workspace_path=None)[source]¶

Read AGY’s MCP config files and return any upstream MCP servers found.

Parameters:: workspace_path (Path | None) – Optional workspace path for workspace-level AGY config.
Returns:: Tuple of UpstreamMcpServer objects found in AGY config files.
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.load_existing_claude_upstream_servers(workspace_path=None)[source]¶

Read Claude’s MCP config files and return any upstream MCP servers found.

Parameters:: workspace_path (Path | None)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.mcp_toml_as_upstreams(workspace_path)[source]¶

Load .agent/mcp.toml and return the configured upstream MCP servers.

Parameters:: workspace_path (Path | None)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.merge_mcp_toml_into_upstreams(agent_native, mcp_toml_servers)[source]¶

Merge mcp.toml servers into agent-native upstreams, preferring mcp.toml on conflict.

Parameters:

agent_native (tuple[UpstreamMcpServer, ...])
mcp_toml_servers (tuple[UpstreamMcpServer, ...])

Return type:

tuple[UpstreamMcpServer, …]

ralph.mcp.transport.merge_opencode_config_content(existing, endpoint)[source]¶

Merge Ralph MCP endpoint into an existing OpenCode config and return JSON.

Parameters:

existing (str | None)
endpoint (str)

Return type:

str

ralph.mcp.transport.prepare_codex_home(endpoint, *, workspace_path, existing_home, system_prompt_file)[source]¶

Prepare an isolated Codex home directory and return its path.

Parameters:

endpoint (str | None)
workspace_path (Path | None)
existing_home (str | None)
system_prompt_file (str | None)

Return type:

str

ralph.mcp.transport.prepare_codex_home_with_upstreams(endpoint, *, workspace_path, existing_home, system_prompt_file)[source]¶

Prepare an isolated Codex home directory and return its path with upstream servers.

Parameters:

endpoint (str | None)
workspace_path (Path | None)
existing_home (str | None)
system_prompt_file (str | None)

Return type:

tuple[str, tuple[UpstreamMcpServer, …]]

ralph.mcp.transport.set_upstream_mcp_config(runtime_env, upstreams)[source]¶

Inject upstream MCP config into the runtime environment dict.

Parameters:

runtime_env (dict[str, str])
upstreams (tuple[UpstreamMcpServer, ...])

Return type:

None

ralph.mcp.transport.claude¶

Claude-specific MCP transport helpers.

ralph.mcp.transport.claude.claude_mcp_config(endpoint, *, workspace_path=None)[source]¶

Return the Claude MCP JSON config string pointing to the given endpoint.

Parameters:

endpoint (str)
workspace_path (Path | None)

Return type:

str

ralph.mcp.transport.claude.load_existing_claude_upstream_servers(workspace_path=None)[source]¶

Read Claude’s MCP config files and return any upstream MCP servers found.

Parameters:: workspace_path (Path | None)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.codex¶

Codex-specific MCP transport helpers.

ralph.mcp.transport.codex.prepare_codex_home(endpoint, *, workspace_path, existing_home, system_prompt_file)[source]¶

Prepare an isolated Codex home directory and return its path.

Parameters:

endpoint (str | None)
workspace_path (Path | None)
existing_home (str | None)
system_prompt_file (str | None)

Return type:

str

ralph.mcp.transport.codex.prepare_codex_home_with_upstreams(endpoint, *, workspace_path, existing_home, system_prompt_file)[source]¶

Prepare an isolated Codex home directory and return its path with upstream servers.

Parameters:

endpoint (str | None)
workspace_path (Path | None)
existing_home (str | None)
system_prompt_file (str | None)

Return type:

tuple[str, tuple[UpstreamMcpServer, …]]

ralph.mcp.transport.common¶

Shared MCP transport helpers: mcp.toml loading, upstream merging, env serialization.

ralph.mcp.transport.common.mcp_config_as_upstreams(mcp_config)[source]¶

Convert loaded MCP config into Ralph custom upstream server records.

Parameters:: mcp_config (McpConfig)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.common.mcp_toml_as_upstreams(workspace_path)[source]¶

Load .agent/mcp.toml and return the configured upstream MCP servers.

Parameters:: workspace_path (Path | None)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.transport.common.merge_mcp_toml_into_upstreams(agent_native, mcp_toml_servers)[source]¶

Merge mcp.toml servers into agent-native upstreams, preferring mcp.toml on conflict.

Parameters:

agent_native (tuple[UpstreamMcpServer, ...])
mcp_toml_servers (tuple[UpstreamMcpServer, ...])

Return type:

tuple[UpstreamMcpServer, …]

ralph.mcp.transport.common.set_upstream_mcp_config(runtime_env, upstreams)[source]¶

Inject upstream MCP config into the runtime environment dict.

Parameters:

runtime_env (dict[str, str])
upstreams (tuple[UpstreamMcpServer, ...])

Return type:

None

ralph.mcp.transport.opencode¶

OpenCode-specific MCP transport helpers.

ralph.mcp.transport.opencode.build_opencode_provider_config(existing, endpoint)[source]¶

Build a full OpenCode config JSON with Ralph MCP and return it with upstream servers.

Parameters:

existing (str | None)
endpoint (str)

Return type:

tuple[str, tuple[UpstreamMcpServer, …]]

ralph.mcp.transport.opencode.merge_opencode_config_content(existing, endpoint)[source]¶

Merge Ralph MCP endpoint into an existing OpenCode config and return JSON.

Parameters:

existing (str | None)
endpoint (str)

Return type:

str

ralph.mcp.transport.agy¶

Google Anti Gravity (AGY) transport helpers.

This module provides AGY-specific MCP transport helpers.

Research-confirmed facts: - Executable: agy - Print flag: –print - Yolo flag: –dangerously-skip-permissions - MCP config path: ~/.gemini/antigravity-cli/mcp_config.json - HTTP JSON key: serverUrl - Output format: plain text (not NDJSON) - uses JsonParserType.GENERIC

Ralph reads existing AGY upstream servers from the user config files at ~/.gemini/antigravity-cli/mcp_config.json and workspace .agents/mcp_config.json. The agy_mcp_config() helper builds the AGY-native JSON payload for Ralph’s MCP endpoint using AGY’s serverUrl field.

ralph.mcp.transport.agy.agy_mcp_config(endpoint)[source]¶

Return the AGY MCP JSON config string pointing to the given endpoint.

Parameters:: endpoint (str) – The MCP server HTTP endpoint URL.
Returns:: JSON string with mcpServers containing the Ralph entry with serverUrl key.
Return type:: str

ralph.mcp.transport.agy.agy_workspace_mcp_endpoint(workspace_path, endpoint)[source]¶

Write a run-scoped Ralph-only MCP config for AGY and restore it after exit.

Parameters:

workspace_path (Path)
endpoint (str)

Return type:

Iterator[None]

ralph.mcp.transport.agy.load_existing_agy_upstream_servers(workspace_path=None)[source]¶

Read AGY’s MCP config files and return any upstream MCP servers found.

Parameters:: workspace_path (Path | None) – Optional workspace path for workspace-level AGY config.
Returns:: Tuple of UpstreamMcpServer objects found in AGY config files.
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.upstream¶

Upstream MCP client and validation.

This sub-package handles Ralph’s outbound MCP traffic: Ralph acts as an MCP client when talking to user-defined upstream servers in mcp.toml. Contains the HTTP/stdio client, server registry, validation handshake, and per-agent transport probe.

ralph.mcp.upstream.agent_probe¶

Probe per-agent MCP wiring against validated upstream servers.

After ralph.mcp.upstream.validation has confirmed that each upstream MCP server is reachable from Ralph, this module synthesizes the agent-specific config payload Ralph would emit for Claude/Codex/OpenCode/AGY and re-runs the same MCP handshake to confirm the wire is shaped correctly.

The probe is self-contained: it never spawns the agent binaries themselves. The MCP JSON-RPC handshake is identical across the supported agents so Ralph’s own client is a faithful reference implementation.

class ralph.mcp.upstream.agent_probe.AgentProbeReport(transport, server_name, ok, error=None, note=None)[source]¶

Bases: object

Result of probing one (transport, upstream server) combination.

Parameters:

transport (AgentTransport)
server_name (str)
ok (bool)
error (str | None)
note (str | None)

exception ralph.mcp.upstream.agent_probe.AgentTransportProbeError[source]¶

Bases: RuntimeError

Raised when the synthesized agent config payload is malformed.

ralph.mcp.upstream.agent_probe.probe_agent_transports(servers, *, transports=(AgentTransport.CLAUDE, AgentTransport.CLAUDE_INTERACTIVE, AgentTransport.CODEX, AgentTransport.OPENCODE, AgentTransport.AGY), workspace_path=None, timeout=None)[source]¶

Confirm Ralph’s per-agent MCP wiring reaches each server.

Parameters:

servers (Iterable[UpstreamMcpServer]) – Iterable of validated upstream servers.
transports (Iterable[AgentTransport]) – Agent transports to probe. Defaults to all supported.
workspace_path (Path | None) – Optional workspace path used by Codex prep helpers.
timeout (timedelta | None) – Reserved; subprocess and HTTP probes use the per-call timeout configured via RALPH_MCP_PREFLIGHT_TIMEOUT_MS.

Returns:

One report per (transport, server) pair.

Return type:

tuple[AgentProbeReport, …]

ralph.mcp.upstream.client¶

HTTP and stdio clients for proxying calls to upstream MCP servers.

Provides HttpUpstreamClient and StdioUpstreamClient, both implementing UpstreamMcpClient. make_upstream_client selects the right implementation from the server’s transport field. Internal helpers handle JSON-RPC framing, legacy SSE endpoints, and multimodal content-block normalization.

Multimodal normalization is done at the registry level via normalize_upstream_content_blocks(), not inside individual clients.

class ralph.mcp.upstream.client.HasMediaManifest(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for upstream clients that expose a media artifact manifest.

class ralph.mcp.upstream.client.HttpUpstreamClient(server, *, caller=None)[source]¶

Bases: object

Upstream MCP client that communicates over HTTP JSON-RPC.

Parameters:

server (UpstreamMcpServer)
caller (JsonRpcCaller | None)

class ralph.mcp.upstream.client.StdioUpstreamClient(server, *, caller=None)[source]¶

Bases: object

Upstream MCP client that communicates over stdio with a subprocess.

Parameters:

server (UpstreamMcpServer)
caller (JsonRpcCaller | None)

exception ralph.mcp.upstream.client.UpstreamCallError[source]¶

Bases: Exception

Raised when a remote tool call or upstream server reachability check fails.

class ralph.mcp.upstream.client.UpstreamMcpClient(*args, **kwargs)[source]¶

Bases: Protocol

Protocol satisfied by both HTTP and stdio upstream MCP client implementations.

ralph.mcp.upstream.client.make_upstream_client(server, *, caller=None)[source]¶

Instantiate the appropriate upstream client for the server’s transport.

Parameters:

server (UpstreamMcpServer)
caller (JsonRpcCaller | None)

Return type:

ralph.mcp.upstream.client.normalize_upstream_content_blocks(result, server_name, tool_name, session=None)[source]¶

Normalize upstream tool result content blocks into the multimodal contract.

text blocks: pass through unchanged.
resource_reference blocks: pass through unchanged.
image/audio/video/pdf/document blocks: normalized to resource_reference. URI-backed blocks preserve the upstream URI; embedded-data blocks store bytes in the session manifest (ralph://media/… URI) when available.
Other types: raise UpstreamCallError with a clear explanation.

Modifies the result dict in place.

Parameters:

result (dict[str, object])
server_name (str)
tool_name (str)
session (HasMediaManifest | None)

Return type:

None

ralph.mcp.upstream.config¶

Transport-neutral upstream MCP config normalization helpers.

class ralph.mcp.upstream.config.UpstreamMcpServer(name, transport, url=None, command=None, args=(), env=<factory>, origin='agent_upstream')[source]¶

Bases: object

Normalized upstream MCP server definition for Ralph runtime use.

Parameters:

name (str)
transport (Literal['http', 'stdio'])
url (str | None)
command (str | None)
args (tuple[str, ...])
env (dict[str, str])
origin (Literal['custom', 'agent_upstream'])

ralph.mcp.upstream.config.load_upstream_mcp_servers(raw)[source]¶

Decode upstream MCP servers from their serialized environment payload.

Parameters:: raw (str | None)
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.upstream.config.load_upstream_tool_catalog(raw)[source]¶

Decode upstream tool metadata from its serialized environment payload.

Parameters:: raw (str | None)
Return type:: dict[str, list[UpstreamTool]]

ralph.mcp.upstream.config.normalize_upstream_mcp_servers(server_entries)[source]¶

Normalize provider-specific MCP server maps into Ralph runtime definitions.

Parameters:: server_entries (Mapping[str, object])
Return type:: tuple[UpstreamMcpServer, …]

ralph.mcp.upstream.config.serialize_upstream_mcp_servers(servers)[source]¶

Serialize normalized upstream servers for process environment transport.

Parameters:: servers (Iterable[UpstreamMcpServer])
Return type:: str

ralph.mcp.upstream.config.serialize_upstream_tool_catalog(tool_catalog)[source]¶

Serialize discovered upstream tool metadata for process environment transport.

Parameters:: tool_catalog (Mapping[str, Iterable[UpstreamTool]])
Return type:: str

ralph.mcp.upstream.models¶

Data models shared across the upstream MCP client subsystem.

Contains UpstreamTool (description of a single tool advertised by an upstream server) and UpstreamCallError (raised when a remote tool call or server reachability check fails).

exception ralph.mcp.upstream.models.UpstreamCallError[source]¶

Bases: Exception

Raised when a remote tool call or upstream server reachability check fails.

class ralph.mcp.upstream.models.UpstreamTool(name, description, input_schema=<factory>)[source]¶

Bases: object

A tool advertised by an upstream MCP server.

Parameters:

name (str)
description (str)
input_schema (dict[str, object])

ralph.mcp.upstream.registry¶

Registry that aggregates tools from multiple upstream MCP servers.

UpstreamRegistry is built from a list of configured UpstreamMcpServer entries; it contacts each server, collects its tool list, assigns stable alias names via upstream_proxy_tool_name, and exposes tool_definitions and call_tool for use by the MCP bridge. Alias collisions raise RegistryCollisionError immediately.

class ralph.mcp.upstream.registry.ProxiedTool(alias, server_name, tool)[source]¶

Bases: object

A single upstream tool mapped to a stable proxy alias.

Parameters:

alias (str)
server_name (str)
tool (UpstreamTool)

exception ralph.mcp.upstream.registry.RegistryCollisionError[source]¶

Bases: ValueError

Raised when two upstream servers produce the same proxy alias for a tool.

class ralph.mcp.upstream.registry.UpstreamRegistry(proxied_tools, clients)[source]¶

Bases: object

Aggregates tools from multiple upstream MCP servers under stable proxy aliases.

Parameters:

proxied_tools (list[ProxiedTool])
clients (dict[str, _AnyUpstreamClient])

classmethod build_from_tool_catalog(servers, tool_catalog, *, client_factory=None)[source]¶

Build a registry from pre-discovered tools without probing upstreams.

Parameters:

servers (Iterable[UpstreamMcpServer])
tool_catalog (dict[str, list[UpstreamTool]])
client_factory (Callable[[UpstreamMcpServer], HttpUpstreamClient | StdioUpstreamClient] | None)

Return type:

UpstreamRegistry

ralph.mcp.upstream.validation¶

Startup validation for user-defined upstream MCP servers.

Ralph fails fast if any custom MCP server cannot complete the standard initialize → notifications/initialized → tools/list handshake. Set RALPH_MCP_STRICT=0 to fall back to the legacy warn-and-skip behaviour for CI smoke runs.

class ralph.mcp.upstream.validation.UpstreamServerReport(name, transport, ok, tool_count=0, error=None, secret_keys=<factory>)[source]¶

Bases: object

Validation result for a single upstream MCP server.

Parameters:

name (str)
transport (Literal['http', 'stdio'])
ok (bool)
tool_count (int)
error (str | None)
secret_keys (tuple[str, ...])

exception ralph.mcp.upstream.validation.UpstreamValidationError[source]¶

Bases: RuntimeError

Raised in strict mode when one or more upstream MCP servers fail validation.

class ralph.mcp.upstream.validation.UpstreamValidationReport(servers)[source]¶

Bases: object

Aggregated validation results for all configured upstream MCP servers.

Parameters:: servers (tuple[UpstreamServerReport, ...])

ralph.mcp.upstream.validation.strict_mode_from_env(env=None)[source]¶

Return True when strict mode is active (the default).

Parameters:: env (Mapping[str, str] | None)
Return type:: bool

ralph.mcp.upstream.validation.validate_upstream_mcp_servers(servers, *, timeout=None, strict=None, preflight_http=<function preflight_http_mcp_server_tools>, list_stdio_tools=None)[source]¶

Validate every configured upstream MCP server at startup.

Parameters:

servers (Iterable[UpstreamMcpServer]) – Iterable of normalized upstream MCP server definitions.
timeout (timedelta | None) – Optional preflight timeout. Defaults to mcp_preflight_timeout_from_env() (30s, tunable via RALPH_MCP_PREFLIGHT_TIMEOUT_MS).
strict (bool | None) – Override strict-mode autodetection. If unset, reads RALPH_MCP_STRICT from the environment.
preflight_http (HttpPreflightFn) – Injection point for the HTTP preflight helper. Tests override this to drive the validator without touching the network.
list_stdio_tools (Callable[[UpstreamMcpServer, timedelta], list[str]] | None) – Injection point for the stdio probe. Defaults to _list_stdio_tools(), which spawns the configured command through StdioUpstreamClient.

Returns:

UpstreamValidationReport with one entry per server. In soft mode failures are reported with ok=False and a warning is logged per failure. In strict mode an UpstreamValidationError is raised after all servers are inspected so the diagnostic listing names every problem at once.

Return type:

UpstreamValidationReport

ralph.mcp.webvisit¶

Web visit capability: single-page URL fetch and readable text extraction.

This package implements the visit_url MCP tool that agents use to fetch and read web pages. It fetches a single URL over HTTP/HTTPS, extracts readable text from the HTML, and returns the content as Markdown-like plain text.

Main entry points:

ralph.mcp.webvisit.fetcher — HTTP fetch layer; sends the request, follows redirects, and enforces the allowed-scheme/SSRF guard.
ralph.mcp.webvisit.extractor — HTML-to-text extraction; strips scripts, styles, and navigation boilerplate and returns readable body text.

This package is a pure back-end implementation; the MCP tool registration lives in ralph.mcp.tools.webvisit. It does not support multi-page crawling; for that, see the upstream Crawl4AI/Firecrawl configuration described in the Local Web Access docs.

ralph.mcp.webvisit.extractor¶

HTML text extraction for the visit_url tool.

Uses readability-lxml for main-content isolation and selectolax for fast plain-text rendering. Both dependencies are optional ([web-visit] extras).

class ralph.mcp.webvisit.extractor.ExtractedPage(title, text, links)[source]¶

Bases: object

Result of extracting readable content from an HTML page.

Parameters:

title (str | None)
text (str)
links (tuple[str, ...])

ralph.mcp.webvisit.extractor.extract_readable(html, *, base_url, with_links)[source]¶

Extract readable text and optional links from raw HTML.

Requires the [web-visit] extras: pip install ralph-workflow[web-visit]

Parameters:

html (str)
base_url (str | None)
with_links (bool)

Return type:

ExtractedPage

ralph.mcp.webvisit.fetcher¶

HTTP fetch layer for the visit_url tool.

Performs a single HTTP GET with SSRF-guard, size cap, and timeout enforcement. No network IO should escape this module in production code paths.

class ralph.mcp.webvisit.fetcher.FetchOutcome(status, effective_url=None, http_status=None, content_type=None, body=None, error=None)[source]¶

Bases: object

Result of a single HTTP fetch attempt.

Parameters:

status (Literal['ok', 'timeout', 'unreachable', 'http_error', 'unsupported_content', 'too_large', 'blocked_by_policy', 'invalid_url'])
effective_url (str | None)
http_status (int | None)
content_type (str | None)
body (bytes | None)
error (str | None)

ralph.mcp.webvisit.fetcher.fetch_url(url, *, timeout_ms, max_bytes, user_agent, allow_private_networks)[source]¶

Fetch a single URL and return a FetchOutcome.

Never raises on network failures — always returns a FetchOutcome.

Parameters:

url (str)
timeout_ms (int)
max_bytes (int)
user_agent (str)
allow_private_networks (bool)

Return type:

FetchOutcome

ralph.mcp.websearch¶

Web-search backends and helpers for the MCP web_search tool.

ralph.mcp.websearch.backends¶

Concrete web-search backend implementations.

ralph.mcp.websearch.backends.base¶

Shared web-search backend abstractions.

class ralph.mcp.websearch.backends.base.SearchResult(title, url, snippet)[source]¶

Bases: object

Normalized search result shape shared by all backends.

Parameters:

title (str)
url (str)
snippet (str)

class ralph.mcp.websearch.backends.base.WebSearchBackend(*args, **kwargs)[source]¶

Bases: Protocol

Protocol implemented by concrete web-search backends.

exception ralph.mcp.websearch.backends.base.WebSearchError[source]¶

Bases: RuntimeError

Raised when a web-search backend fails.

ralph.mcp.websearch.backends.brave¶

Brave Search web-search backend.

class ralph.mcp.websearch.backends.brave.BraveBackend(api_key=None, api_key_env=None, url='https://api.search.brave.com/res/v1/web/search')[source]¶

Bases: object

Backend powered by Brave Search’s HTTP API.

Parameters:

api_key (str | None)
api_key_env (str | None)
url (str)

ralph.mcp.websearch.backends.ddgs¶

DuckDuckGo Search backend implementation.

class ralph.mcp.websearch.backends.ddgs.DdgsBackend[source]¶

Bases: object

In-process default backend backed by the ddgs package.

ralph.mcp.websearch.backends.exa¶

Exa web-search backend.

Implements the ExaBackend dataclass that wraps the exa-py Python SDK to deliver web-search results via the Exa API. Requires pip install ralph-workflow[web-search] (or pip install exa-py) at runtime; importing this module without the SDK installed is safe, but calling search raises WebSearchError.

API key resolution:

Pass api_key directly, or
set api_key_env to an environment variable name that holds the key (resolved via ralph.mcp.websearch.secrets.resolve_secret).

Typical usage (from ralph.config.mcp_models backend selection):

backend = ExaBackend(api_key_env="EXA_API_KEY")
results = backend.search("async Python tutorial", limit=5)

class ralph.mcp.websearch.backends.exa.ExaBackend(api_key=None, api_key_env=None)[source]¶

Bases: object

Backend powered by the Exa Python SDK.

Parameters:

api_key (str | None)
api_key_env (str | None)

ralph.mcp.websearch.backends.searxng¶

SearXNG web-search backend.

Implements the SearxngBackend dataclass that queries a self-hosted SearXNG instance over HTTP. Unlike the API-key backends (Exa, Tavily, Brave), this backend requires no credentials — only the base URL of a running SearXNG server.

The backend POSTs to {url}/search?format=json with a 10-second timeout and normalises the JSON response into a list of SearchResult objects. Network errors and non-200 responses raise WebSearchError.

Typical usage (from ralph.config.mcp_models backend selection):

backend = SearxngBackend(url="http://localhost:8080")
results = backend.search("Python type hints", limit=5)

class ralph.mcp.websearch.backends.searxng.SearxngBackend(url)[source]¶

Bases: object

Backend that queries a user-managed SearXNG instance.

Parameters:: url (str)

ralph.mcp.websearch.backends.tavily¶

Tavily web-search backend.

Implements the TavilyBackend dataclass that wraps the tavily-python SDK to deliver web-search results via the Tavily API. Requires pip install ralph-workflow[web-search] (or pip install tavily-python) at runtime; importing without the SDK is safe, but calling search raises WebSearchError.

API key resolution:

Pass api_key directly, or
set api_key_env to an environment variable name that holds the key (resolved via ralph.mcp.websearch.secrets.resolve_secret).

Typical usage (from ralph.config.mcp_models backend selection):

backend = TavilyBackend(api_key_env="TAVILY_API_KEY")
results = backend.search("FastAPI dependency injection", limit=5)

class ralph.mcp.websearch.backends.tavily.TavilyBackend(api_key=None, api_key_env=None)[source]¶

Bases: object

Backend powered by the Tavily Python SDK.

Parameters:

api_key (str | None)
api_key_env (str | None)

ralph.mcp.websearch.secrets¶

Secret resolution helpers for web-search backends.

ralph.mcp.websearch.secrets.resolve_secret(api_key, api_key_env, *, getenv=<function getenv>)[source]¶

Resolve a backend secret from either an inline value or an env var name.

Parameters:

api_key (str | None)
api_key_env (str | None)
getenv (EnvGetter)

Return type:

str

Git¶

ralph.git¶

Public Git helpers for Ralph.

This package exposes the repository operations used by the Python orchestrator, including staging/commit helpers, managed hook installation, and rebase support. Implementation uses GitPython rather than the retired Rust/libgit2 stack.

class ralph.git.GitHelpers[source]¶

Bases: object

Simple placeholder for Git wrapper state tracking.

exception ralph.git.GitOperationError(operation, message)[source]¶

Bases: Exception

Raised when a git operation fails.

Parameters:

operation (str)
message (str)

Return type:

None

operation¶: Name of the operation that failed.

message¶: Error message describing the failure.

class ralph.git.GitRunResult(args, returncode, stdout, stderr)[source]¶

Bases: object

Result of a git subprocess invocation.

Parameters:

args (tuple[str, ...])
returncode (int)
stdout (str)
stderr (str)

ralph.git.append_to_gitignore(repo_root, patterns)[source]¶

Append patterns to .gitignore.

Parameters:

repo_root (Path | str) – Path to the repository root.
patterns (list[str]) – List of patterns to add.

Return type:

None

ralph.git.create_commit(repo_root, message, author_name=None, author_email=None)[source]¶

Create a git commit.

Parameters:

repo_root (Path | str) – Path to the repository root.
message (str) – Commit message.
author_name (str | None) – Optional author name override.
author_email (str | None) – Optional author email override.

Returns:

SHA of the created commit.

Raises:

GitOperationError – If commit fails.

Return type:

str

ralph.git.detect_unauthorized_commit(repo_root)[source]¶

Return True if the HEAD OID no longer matches the stored baseline.

Parameters:: repo_root (Path | str)
Return type:: bool

ralph.git.end_agent_phase(repo_root, helpers=None)[source]¶

Remove agent-phase protections and restore git state.

Parameters:

repo_root (Path | str)
helpers (GitHelpers | None)

Return type:

None

ralph.git.find_repo_root(start=PosixPath('.'))[source]¶

Locate git repo root from start path.

Parameters:: start (Path | str) – Starting path for the search.
Returns:: Path to the repository root.
Raises:: GitOperationError – If not inside a git repository.
Return type:: Path

ralph.git.get_head_sha(repo_root)[source]¶

Return current HEAD commit SHA.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: SHA of the current HEAD commit.
Return type:: str

ralph.git.get_hooks_dir(repo_root=None)[source]¶

Return the git hooks directory for a repository root.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.get_staged_files(repo_root)[source]¶

Get list of staged files.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: List of staged file paths.
Return type:: list[str]

ralph.git.has_staged_changes(repo_root)[source]¶

Check if repository has staged changes.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: True if there are staged changes.
Return type:: bool

ralph.git.install_hooks(repo_root=None)¶

Install the Ralph-managed hooks into a repository.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.install_hooks_in_repo(repo_root=None)[source]¶

Install the Ralph-managed hooks into a repository.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.is_repo_clean(repo_root)[source]¶

Check if repository has uncommitted changes.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: True if repository is clean (no uncommitted changes).
Return type:: bool

ralph.git.merge_base(repo_root, ref_a, ref_b)[source]¶

Return merge-base SHA between two refs.

Parameters:

repo_root (Path | str) – Path to the repository root.
ref_a (str) – First ref (branch, tag, SHA).
ref_b (str) – Second ref (branch, tag, SHA).

Returns:

SHA of the merge base commit.

Raises:

GitOperationError – If merge base cannot be determined.

Return type:

str

ralph.git.push(repo_root, remote='origin', branch=None)[source]¶

Push current branch to remote.

Parameters:

repo_root (Path | str) – Path to the repository root.
remote (str) – Remote name to push to.
branch (str | None) – Optional branch name override.

Raises:

GitOperationError – If push fails.

Return type:

None

ralph.git.reinstall_hooks_if_tampered(*, logger=None, repo_root=None)[source]¶

Reinstall hooks when they are missing or do not contain the marker.

Parameters:

logger (Logger | None)
repo_root (Path | str | None)

Return type:

bool

ralph.git.run_git(args, *, cwd, label, options=None)[source]¶

Spawn a git subprocess through ProcessManager and return the result.

When options.phase is provided the process label becomes phase:<phase>:git:<label> so process_phase_scope can terminate it.

Raises subprocess.TimeoutExpired if timeout is exceeded. Raises subprocess.CalledProcessError if options.check is True and returncode != 0.

Parameters:

args (Sequence[str])
cwd (Path | None)
label (str)
options (GitRunOptions | None)

Return type:

GitRunResult

ralph.git.stage_all(repo_root)[source]¶

Stage all changes (git add -A).

Parameters:: repo_root (Path | str) – Path to the repository root.
Return type:: None

ralph.git.start_agent_phase(repo_root, helpers=None)[source]¶

Enable git protections for an agent phase.

Parameters:

repo_root (Path | str)
helpers (GitHelpers | None)

Return type:

None

ralph.git.uninstall_hooks(*, logger=None, repo_root=None)[source]¶

Remove Ralph-managed hooks from the repository.

Parameters:

logger (Logger | None)
repo_root (Path | str | None)

Return type:

bool

ralph.git.executor¶

GitExecutor — serialized gate for GitPython operations.

GitPython is not thread-safe when multiple threads share a single .git/ directory. GitExecutor wraps all repo-mutating operations in a single-threaded executor, ensuring only one git operation runs at a time regardless of how many asyncio tasks or threads call it concurrently.

class ralph.git.executor.GitExecutor[source]¶

Bases: object

Serialized gate for GitPython operations.

All calls to run() are executed sequentially in a single background thread (max_workers=1), preventing concurrent GitPython access.

_executor¶: Single-threaded executor that serializes all git ops.

async arun(op)[source]¶

Run a git operation asynchronously without blocking the event loop.

Uses loop.run_in_executor which runs op in the thread pool. Combined with max_workers=1, this ensures serialization even from coroutines.

Parameters:: op (Callable[[], T]) – Zero-argument callable returning T.
Returns:: Awaitable result of op().
Return type:: T

run(op)[source]¶

Run a git operation synchronously, serialized with all other ops.

Parameters:: op (Callable[[], T]) – Zero-argument callable returning T.
Returns:: Result of op().
Raises:: Any exception raised by op(). –
Return type:: T

ralph.git.hooks¶

Manage Ralph git hooks for the Python CLI.

ralph.git.hooks.HOOK_MARKER = 'RALPH_RUST_MANAGED_HOOK'¶: Marker string embedded in every Ralph-managed hook.

ralph.git.hooks.RALPH_HOOK_NAMES = ('pre-commit', 'pre-push', 'pre-merge-commit', 'commit-msg')¶: Hook names managed by Ralph workflows.

ralph.git.hooks.get_hooks_dir(repo_root=None)[source]¶

Return the git hooks directory for a repository root.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.hooks.install_hooks(repo_root=None)¶

Install the Ralph-managed hooks into a repository.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.hooks.install_hooks_in_repo(repo_root=None)[source]¶

Install the Ralph-managed hooks into a repository.

Parameters:: repo_root (Path | str | None)
Return type:: Path

ralph.git.hooks.reinstall_hooks_if_tampered(*, logger=None, repo_root=None)[source]¶

Reinstall hooks when they are missing or do not contain the marker.

Parameters:

logger (Logger | None)
repo_root (Path | str | None)

Return type:

bool

ralph.git.hooks.uninstall_hooks(*, logger=None, repo_root=None)[source]¶

Remove Ralph-managed hooks from the repository.

Parameters:

logger (Logger | None)
repo_root (Path | str | None)

Return type:

bool

ralph.git.operations¶

Git operations for ralph pipeline via GitPython.

This module provides a high-level interface for git operations, wrapping GitPython to provide the functionality needed by the pipeline.

exception ralph.git.operations.GitOperationError(operation, message)[source]¶

Bases: Exception

Raised when a git operation fails.

Parameters:

operation (str)
message (str)

Return type:

None

operation¶: Name of the operation that failed.

message¶: Error message describing the failure.

ralph.git.operations.append_to_gitignore(repo_root, patterns)[source]¶

Append patterns to .gitignore.

Parameters:

repo_root (Path | str) – Path to the repository root.
patterns (list[str]) – List of patterns to add.

Return type:

None

ralph.git.operations.create_commit(repo_root, message, author_name=None, author_email=None)[source]¶

Create a git commit.

Parameters:

repo_root (Path | str) – Path to the repository root.
message (str) – Commit message.
author_name (str | None) – Optional author name override.
author_email (str | None) – Optional author email override.

Returns:

SHA of the created commit.

Raises:

GitOperationError – If commit fails.

Return type:

str

ralph.git.operations.find_main_worktree_root(start=PosixPath('.'))[source]¶

Find the primary worktree root for the current repository.

For linked worktrees, this resolves to the main checkout that owns the shared git common directory. For ordinary repositories, it matches the active repository root.

This helper detects linked git worktrees only as a workspace-root resolver and is NEVER used by the same-workspace parallel worker path. Parallel v1 workers always share the canonical repo_root; this function MUST NOT be invoked by ralph.pipeline.parallel.* modules. Callers in that package violate the same-workspace isolation contract.

Parameters:: start (Path | str)
Return type:: Path

ralph.git.operations.find_repo_root(start=PosixPath('.'))[source]¶

Locate git repo root from start path.

Parameters:: start (Path | str) – Starting path for the search.
Returns:: Path to the repository root.
Raises:: GitOperationError – If not inside a git repository.
Return type:: Path

ralph.git.operations.get_commits_between(repo_root, from_ref, to_ref)[source]¶

Get list of commit SHAs between two refs.

Parameters:

repo_root (Path | str) – Path to the repository root.
from_ref (str) – Starting ref (exclusive).
to_ref (str) – Ending ref (inclusive).

Returns:

List of commit SHAs in reverse chronological order.

Return type:

list[str]

ralph.git.operations.get_current_branch(repo_root)[source]¶

Get the current branch name.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: Name of the current branch.
Return type:: str

ralph.git.operations.get_head_sha(repo_root)[source]¶

Return current HEAD commit SHA.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: SHA of the current HEAD commit.
Return type:: str

ralph.git.operations.get_staged_files(repo_root)[source]¶

Get list of staged files.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: List of staged file paths.
Return type:: list[str]

ralph.git.operations.has_commits_since(repo_root, baseline_sha)[source]¶

Return True when HEAD is ahead of baseline_sha.

When baseline_sha is None the caller has no prior baseline (first run), so we conservatively return True to allow the caller to proceed.

Parameters:

repo_root (Path | str)
baseline_sha (str | None)

Return type:

bool

ralph.git.operations.has_staged_changes(repo_root)[source]¶

Check if repository has staged changes.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: True if there are staged changes.
Return type:: bool

ralph.git.operations.has_uncommitted_changes(repo_root)[source]¶

Return True when the working tree has uncommitted work.

Includes staged diff, unstaged diff, and untracked files. This is the authoritative skip check for commit phases: if this returns False, there is literally nothing for a commit agent to package up.

Parameters:: repo_root (Path | str)
Return type:: bool

ralph.git.operations.is_repo_clean(repo_root)[source]¶

Check if repository has uncommitted changes.

Parameters:: repo_root (Path | str) – Path to the repository root.
Returns:: True if repository is clean (no uncommitted changes).
Return type:: bool

ralph.git.operations.merge_base(repo_root, ref_a, ref_b)[source]¶

Return merge-base SHA between two refs.

Parameters:

repo_root (Path | str) – Path to the repository root.
ref_a (str) – First ref (branch, tag, SHA).
ref_b (str) – Second ref (branch, tag, SHA).

Returns:

SHA of the merge base commit.

Raises:

GitOperationError – If merge base cannot be determined.

Return type:

str

ralph.git.operations.push(repo_root, remote='origin', branch=None)[source]¶

Push current branch to remote.

Parameters:

repo_root (Path | str) – Path to the repository root.
remote (str) – Remote name to push to.
branch (str | None) – Optional branch name override.

Raises:

GitOperationError – If push fails.

Return type:

None

ralph.git.operations.stage_all(repo_root)[source]¶

Stage all changes (git add -A).

Parameters:: repo_root (Path | str) – Path to the repository root.
Return type:: None

ralph.git.operations.stage_files(repo_root, files)[source]¶

Stage only the provided repository-relative paths.

Uses git add --all -- <paths> so modified, untracked, and deleted files are all handled consistently for the selected scope.

Parameters:

repo_root (Path | str)
files (list[str])

Return type:

None

ralph.git.rebase¶

Rebase-specific helpers for git operations.

ralph.git.rebase.rebase¶

Core git rebase helpers (abort/continue/rebase).

class ralph.git.rebase.rebase.ProcessExecutor(*args, **kwargs)[source]¶

Bases: Protocol

Executor that runs external processes.

class ralph.git.rebase.rebase.ProcessResult(returncode, stdout, stderr)[source]¶

Bases: object

Represents the result of running a git subprocess.

Parameters:

returncode (int)
stdout (str)
stderr (str)

class ralph.git.rebase.rebase.RebaseConflicts(files)[source]¶

Bases: object

Rebase stopped because conflicts remain.

Parameters:: files (list[str])

class ralph.git.rebase.rebase.RebaseFailed(kind)[source]¶

Bases: object

Rebase failed with a specific error kind.

Parameters:: kind (RebaseErrorKind)

class ralph.git.rebase.rebase.RebaseNoOp(reason)[source]¶

Bases: object

Rebase was not applicable (already up-to-date or invalid state).

Parameters:: reason (str)

exception ralph.git.rebase.rebase.RebaseOperationError[source]¶

Bases: Exception

Raised when a rebase operation fails.

class ralph.git.rebase.rebase.RebaseSuccess[source]¶

Bases: object

Rebase completed successfully.

class ralph.git.rebase.rebase.SubprocessExecutor[source]¶

Bases: object

Default executor powered by run_git.

ralph.git.rebase.rebase.abort_rebase(*, repo_root=None, executor=None)[source]¶

Abort an in-progress rebase.

Parameters:

repo_root (Path | str | None)
executor (ProcessExecutor | None)

Return type:

None

ralph.git.rebase.rebase.continue_rebase(*, repo_root=None, executor=None)[source]¶

Continue an in-progress rebase after conflicts have been resolved.

Parameters:

repo_root (Path | str | None)
executor (ProcessExecutor | None)

Return type:

None

ralph.git.rebase.rebase.get_conflicted_files(*, repo_root=None, executor=None)[source]¶

List files that are currently marked as conflicted in the index.

Parameters:

repo_root (Path | str | None)
executor (ProcessExecutor | None)

Return type:

list[str]

ralph.git.rebase.rebase.rebase_in_progress(repo_root=None)[source]¶

Return True when a rebase directory exists in the git repo.

Parameters:: repo_root (Path | str | None)
Return type:: bool

ralph.git.rebase.rebase.rebase_onto(upstream_branch, *, repo_root=None, executor=None)[source]¶

Rebase the current branch on top of the provided upstream branch.

Parameters:

upstream_branch (str)
repo_root (Path | str | None)
executor (ProcessExecutor | None)

Return type:

RebaseSuccess | RebaseConflicts | RebaseNoOp | RebaseFailed

ralph.git.rebase.rebase_checkpoint¶

Rebase checkpoint persistence and locking utilities.

class ralph.git.rebase.rebase_checkpoint.RebaseCheckpoint(phase=<factory>, upstream_branch='', conflicted_files=<factory>, resolved_files=<factory>, error_count=0, last_error=None, timestamp=<factory>, phase_error_count=0)[source]¶

Bases: object

Persisted state for a rebase operation, written to .agent/rebase_checkpoint.json.

Parameters:

phase (RebasePhase)
upstream_branch (str)
conflicted_files (list[str])
resolved_files (list[str])
error_count (int)
last_error (str | None)
timestamp (str)
phase_error_count (int)

ralph.git.rebase.rebase_checkpoint.acquire_rebase_lock()[source]¶

Acquire the rebase lock file, raising OSError if another process holds it.

Return type:: None

ralph.git.rebase.rebase_checkpoint.clear_rebase_checkpoint()[source]¶

Delete the rebase checkpoint file if it exists.

Return type:: None

ralph.git.rebase.rebase_checkpoint.load_rebase_checkpoint()[source]¶

Load and validate the rebase checkpoint, falling back to backup on error.

Return type:: RebaseCheckpoint | None

ralph.git.rebase.rebase_checkpoint.rebase_checkpoint_exists()[source]¶

Return True if a rebase checkpoint file exists on disk.

Return type:: bool

ralph.git.rebase.rebase_checkpoint.release_rebase_lock()[source]¶

Release the rebase lock file if it exists.

Return type:: None

ralph.git.rebase.rebase_checkpoint.restore_from_backup()[source]¶

Attempt to restore a valid checkpoint from the backup file.

Return type:: RebaseCheckpoint | None

ralph.git.rebase.rebase_checkpoint.save_rebase_checkpoint(checkpoint)[source]¶

Atomically persist checkpoint to the agent rebase checkpoint file.

Parameters:: checkpoint (RebaseCheckpoint)
Return type:: None

ralph.git.rebase.rebase_continuation¶

Helpers for continuing paused Git rebases.

exception ralph.git.rebase.rebase_continuation.ConflictRemainingError[source]¶

Bases: RebaseContinuationError

Raised when conflicts remain while attempting to continue.

exception ralph.git.rebase.rebase_continuation.NoRebaseInProgressError[source]¶

Bases: RebaseContinuationError

Raised when no rebase is active but continuation was requested.

exception ralph.git.rebase.rebase_continuation.RebaseContinuationError[source]¶

Bases: Exception

Base exception for rebase continuation helpers.

exception ralph.git.rebase.rebase_continuation.RebaseVerificationError[source]¶

Bases: Exception

Raised when verifying rebase completion fails.

ralph.git.rebase.rebase_continuation.continue_rebase(repo_root=None)[source]¶

Resume a paused rebase, auto-detecting the repo root.

Parameters:: repo_root (Path | str | None)
Return type:: None

ralph.git.rebase.rebase_continuation.continue_rebase_at(repo_root)[source]¶

Resume a paused rebase at repo_root, raising if conflicts remain.

Parameters:: repo_root (Path | str)
Return type:: None

ralph.git.rebase.rebase_continuation.rebase_in_progress(repo_root=None)[source]¶

Return True if a git rebase is in progress, auto-detecting the repo root.

Parameters:: repo_root (Path | str | None)
Return type:: bool

ralph.git.rebase.rebase_continuation.rebase_in_progress_at(repo_root)[source]¶

Return True if a git rebase is currently in progress at repo_root.

Parameters:: repo_root (Path | str)
Return type:: bool

ralph.git.rebase.rebase_continuation.verify_rebase_completed(upstream_branch, repo_root=None)[source]¶

Verify rebase completion, auto-detecting the repo root.

Parameters:

upstream_branch (str)
repo_root (Path | str | None)

Return type:

bool

ralph.git.rebase.rebase_continuation.verify_rebase_completed_at(repo_root, upstream_branch)[source]¶

Return True if the rebase is complete and HEAD is a descendant of upstream_branch.

Parameters:

repo_root (Path | str)
upstream_branch (str)

Return type:

bool

ralph.git.rebase.rebase_kinds¶

Classification helpers for Git rebase outcomes.

class ralph.git.rebase.rebase_kinds.RebaseErrorKind(kind, metadata=<factory>)[source]¶

Bases: object

Payload for a classified rebase failure.

Parameters:

kind (RebaseKind)
metadata (Mapping[str, object])

class ralph.git.rebase.rebase_kinds.RebaseKind(*values)[source]¶

Bases: Enum

Enum describing every supported rebase failure mode.

ralph.git.rebase.rebase_kinds.classify_rebase_error(stderr, stdout)[source]¶

Translate git rebase stderr/stdout into a concrete rebase failure kind.

Parameters:

stderr (str)
stdout (str)

Return type:

RebaseErrorKind

ralph.git.rebase.rebase_preconditions¶

Precondition validation before performing a git rebase.

exception ralph.git.rebase.rebase_preconditions.RebasePreconditionError[source]¶

Bases: Exception

Raised when a rebase cannot start because a precondition failed.

ralph.git.rebase.rebase_preconditions.check_rebase_preconditions(repo_root)[source]¶

Ensure the git repository is ready to start a rebase.

Parameters:: repo_root (Path | str) – Path to the git repository.
Raises:: RebasePreconditionError – When the repository is not ready to rebase.
Return type:: None

ralph.git.rebase.rebase_state_machine¶

High-level rebase state machine for Python agents.

exception ralph.git.rebase.rebase_state_machine.InvalidTransitionError[source]¶

Bases: Exception

Raised when an event is invalid in the current state.

class ralph.git.rebase.rebase_state_machine.RebaseCheckpoint(phase=<factory>, upstream_branch='', conflicted_files=<factory>, resolved_files=<factory>, error_count=0, last_error=None, timestamp=<factory>, phase_error_count=0)[source]¶

Bases: object

Persisted state for a rebase operation, written to .agent/rebase_checkpoint.json.

Parameters:

phase (RebasePhase)
upstream_branch (str)
conflicted_files (list[str])
resolved_files (list[str])
error_count (int)
last_error (str | None)
timestamp (str)
phase_error_count (int)

class ralph.git.rebase.rebase_state_machine.RebaseEvent(*values)[source]¶

Bases: Enum

Events that drive transitions in the RebaseStateMachine.

class ralph.git.rebase.rebase_state_machine.RebaseLock[source]¶

Bases: object

Context manager that acquires and releases the rebase lock.

class ralph.git.rebase.rebase_state_machine.RebasePhase(*values)[source]¶

Bases: StrEnum

Lifecycle phase of an in-progress rebase operation.

class ralph.git.rebase.rebase_state_machine.RebaseStateMachine(checkpoint, *, persist=True, max_recovery_attempts=3)[source]¶

Bases: object

State machine that coordinates rebase lifecycle via RebaseCheckpoint.

Parameters:

checkpoint (RebaseCheckpoint)
persist (bool)
max_recovery_attempts (int)

class ralph.git.rebase.rebase_state_machine.RecoveryAction(*values)[source]¶

Bases: Enum

Decision returned by decide to guide error recovery in a rebase.

ralph.git.rebase.rebase_state_machine.acquire_rebase_lock()[source]¶

Acquire the rebase lock file, raising OSError if another process holds it.

Return type:: None

ralph.git.rebase.rebase_state_machine.clear_rebase_checkpoint()[source]¶

Delete the rebase checkpoint file if it exists.

Return type:: None

ralph.git.rebase.rebase_state_machine.load_rebase_checkpoint()[source]¶

Load and validate the rebase checkpoint, falling back to backup on error.

Return type:: RebaseCheckpoint | None

ralph.git.rebase.rebase_state_machine.rebase_checkpoint_exists()[source]¶

Return True if a rebase checkpoint file exists on disk.

Return type:: bool

ralph.git.rebase.rebase_state_machine.release_rebase_lock()[source]¶

Release the rebase lock file if it exists.

Return type:: None

ralph.git.rebase.rebase_state_machine.restore_from_backup()[source]¶

Attempt to restore a valid checkpoint from the backup file.

Return type:: RebaseCheckpoint | None

ralph.git.rebase.rebase_state_machine.save_rebase_checkpoint(checkpoint)[source]¶

Atomically persist checkpoint to the agent rebase checkpoint file.

Parameters:: checkpoint (RebaseCheckpoint)
Return type:: None

ralph.git.subprocess_runner¶

Synchronous git helper backed by ProcessManager.

class ralph.git.subprocess_runner.GitRunOptions(phase=None, timeout=None, env=None, check=False, capture_output=True, text=True)[source]¶

Bases: object

Options for run_git beyond the required args, cwd, and label.

Parameters:

phase (str | None)
timeout (float | None)
env (Mapping[str, str] | None)
check (bool)
capture_output (bool)
text (bool)

ralph.git.subprocess_runner.run_git(args, *, cwd, label, options=None)[source]¶

Spawn a git subprocess through ProcessManager and return the result.

When options.phase is provided the process label becomes phase:<phase>:git:<label> so process_phase_scope can terminate it.

Raises subprocess.TimeoutExpired if timeout is exceeded. Raises subprocess.CalledProcessError if options.check is True and returncode != 0.

Parameters:

args (Sequence[str])
cwd (Path | None)
label (str)
options (GitRunOptions | None)

Return type:

GitRunResult

ralph.git.wrapper¶

Git wrapper helpers for blocking commits during agent phases.

class ralph.git.wrapper.GitHelpers[source]¶

Bases: object

Simple placeholder for Git wrapper state tracking.

ralph.git.wrapper.detect_unauthorized_commit(repo_root)[source]¶

Return True if the HEAD OID no longer matches the stored baseline.

Parameters:: repo_root (Path | str)
Return type:: bool

ralph.git.wrapper.end_agent_phase(repo_root, helpers=None)[source]¶

Remove agent-phase protections and restore git state.

Parameters:

repo_root (Path | str)
helpers (GitHelpers | None)

Return type:

None

ralph.git.wrapper.start_agent_phase(repo_root, helpers=None)[source]¶

Enable git protections for an agent phase.

Parameters:

repo_root (Path | str)
helpers (GitHelpers | None)

Return type:

None

Workspace¶

ralph.workspace¶

Filesystem abstraction exports.

Use Workspace as the protocol shared by production and test code, FsWorkspace for real filesystem access, and MemoryWorkspace for tests that need an in-memory implementation.

ralph.workspace.fs¶

Production filesystem workspace.

This module provides the FsWorkspace implementation that wraps pathlib.Path operations for real filesystem access.

ralph.workspace.memory¶

In-memory workspace for testing.

This module provides the MemoryWorkspace implementation that stores file contents in memory for test isolation.

class ralph.workspace.memory.MemoryWorkspace(root='/workspace')[source]¶

Bases: object

In-memory workspace for test isolation.

This workspace stores all file contents in a dictionary, making it suitable for unit testing without filesystem operations.

All paths are normalized to POSIX-style relative paths.

Parameters:: root (str)

absolute_path(path)[source]¶

Return an absolute-like path string for the workspace.

Parameters:: path (str)
Return type:: str

allowed_roots()[source]¶

Return the list of allowed workspace root paths.

Returns:: List of string paths from configured allowed roots.
Return type:: list[str]

append(path, content)[source]¶

Append content to file.

Parameters:

path (str) – Relative path to the file.
content (str) – Content to append.

Return type:

None

clear()[source]¶

Clear all stored contents.

Return type:: None

copy(src, dest, *, overwrite=False)[source]¶

Copy a file or directory.

Parameters:

src (str) – Source path.
dest (str) – Destination path.
overwrite (bool) – Whether to overwrite existing destination.

Raises:

FileExistsError – If dest exists and overwrite is False.

Return type:

None

create_dir(path)[source]¶

Create a directory.

Parameters:: path (str) – Relative path to the directory.
Return type:: None

delete(path, *, recursive=False)[source]¶

Delete a file or directory.

Parameters:

path (str) – Relative path to delete.
recursive (bool) – If True, delete directories recursively.

Raises:

IsADirectoryError – If path is a directory and recursive is False.

Return type:

None

exists(path)[source]¶

Check if file exists.

Parameters:: path (str) – Relative path to check.
Returns:: True if file exists.
Return type:: bool

is_dir(path)[source]¶

Check if path is a directory.

Parameters:: path (str) – Relative path to check.
Returns:: True if path is a directory.
Return type:: bool

is_file(path)[source]¶

Check if path is a file.

Parameters:: path (str) – Relative path to check.
Returns:: True if path is a file.
Return type:: bool

iter_files(base)[source]¶

Iterate over file paths under a base directory.

Parameters:: base (str) – Base directory path to search under.
Yields:: File paths relative to workspace root, honoring skip patterns.
Return type:: tuple[str, …]

list_dir(path)[source]¶

List directory contents.

Parameters:: path (str) – Relative path to the directory.
Returns:: List of file/directory names.
Return type:: list[str]

mkdirs(path)[source]¶

Create a directory and all parent directories.

Parameters:: path (str) – Relative path to the directory to create.
Return type:: None

move(src, dest, *, overwrite=False)[source]¶

Move a file or directory.

Parameters:

src (str) – Source path.
dest (str) – Destination path.
overwrite (bool) – Whether to overwrite existing destination.

Raises:

FileExistsError – If dest exists and overwrite is False.

Return type:

None

read(path)[source]¶

Read file contents.

Parameters:: path (str) – Relative path to the file.
Returns:: File contents as string.
Raises:: FileNotFoundError – If file doesn’t exist.
Return type:: str

read_bytes(path, *, offset=0, limit=None)[source]¶

Read a byte window from a file, decoded as UTF-8.

Parameters:

path (str)
offset (int)
limit (int | None)

Return type:

tuple[str, dict[str, object]]

read_lines(path, *, start=None, end=None, head=None, tail=None)[source]¶

Read lines from a file with slicing support.

Parameters:

path (str) – Relative path to the file.
start (int | None) – 1-based line number to start from (inclusive).
end (int | None) – 1-based line number to end at (inclusive).
head (int | None) – Return only the first N lines.
tail (int | None) – Return only the last N lines.

Returns:

Tuple of (text content, metadata dict) where metadata has total_lines, returned_lines, truncated keys.

Raises:

ValueError – If conflicting params are supplied.
FileNotFoundError – If file doesn’t exist.

Return type:

tuple[str, dict[str, object]]

remove(path)[source]¶

Remove a file.

Parameters:: path (str) – Relative path to the file.
Return type:: None

stat(path)[source]¶

Get file metadata/stat data.

Parameters:: path (str) – Relative path to the file.
Returns:: Dict with type (‘file’|’dir’|’missing’), size_bytes, created_unix, modified_unix, mode.
Return type:: dict[str, object]

write(path, content)[source]¶

Write content to file.

Parameters:

path (str) – Relative path to the file.
content (str) – Content to write.

Return type:

None

ralph.workspace.protocol¶

Workspace Protocol for file I/O abstraction.

This module defines the Workspace protocol that enables test doubles and in-memory implementations for testing.

class ralph.workspace.protocol.Workspace(*args, **kwargs)[source]¶

Bases: Protocol

File I/O abstraction enabling test doubles.

This protocol defines the interface for file system operations. Implementations can be production (FsWorkspace) or test doubles (MemoryWorkspace).

All paths are relative to the workspace root.

absolute_path(path)[source]¶

Resolve a relative path to its absolute workspace path.

Parameters:: path (str)
Return type:: str

allowed_roots()[source]¶

Return the list of allowed workspace root paths.

Returns:: List of string paths from configured allowed roots.
Return type:: list[str]

append(path, content)[source]¶

Append content to file.

Parameters:

path (str) – Relative path to the file.
content (str) – Content to append.

Return type:

None

copy(src, dest, *, overwrite=False)[source]¶

Copy a file or directory.

Parameters:

src (str) – Source path.
dest (str) – Destination path.
overwrite (bool) – Whether to overwrite existing destination.

Return type:

None

delete(path, *, recursive=False)[source]¶

Delete a file or directory.

Parameters:

path (str) – Relative path to delete.
recursive (bool) – If True, delete directories recursively.

Raises:

IsADirectoryError – If path is a directory and recursive is False.

Return type:

None

exists(path)[source]¶

Check if file exists.

Parameters:: path (str) – Relative path to check.
Returns:: True if file exists.
Return type:: bool

is_dir(path)[source]¶

Check if path is a directory.

Parameters:: path (str) – Relative path to check.
Returns:: True if path is a directory.
Return type:: bool

is_file(path)[source]¶

Check if path is a file.

Parameters:: path (str) – Relative path to check.
Returns:: True if path is a file.
Return type:: bool

iter_files(base)[source]¶

Iterate over file paths under a base directory.

Parameters:: base (str) – Base directory path to search under.
Yields:: File paths relative to workspace root, honoring skip patterns.
Return type:: tuple[str, …]

list_dir(path)[source]¶

List directory contents.

Parameters:: path (str) – Relative path to the directory.
Returns:: List of file/directory names in the directory.
Return type:: list[str]

mkdirs(path)[source]¶

Create a directory and all parent directories.

Parameters:: path (str) – Relative path to the directory to create.
Return type:: None

move(src, dest, *, overwrite=False)[source]¶

Move a file or directory.

Parameters:

src (str) – Source path.
dest (str) – Destination path.
overwrite (bool) – Whether to overwrite existing destination.

Return type:

None

read(path)[source]¶

Read file contents.

Parameters:: path (str) – Relative path to the file.
Returns:: File contents as string.
Raises:: FileNotFoundError – If file doesn’t exist.
Return type:: str

read_bytes(path, *, offset=0, limit=None)[source]¶

Read a byte window from a file, decoded as UTF-8.

Parameters:

path (str) – Relative path to the file.
offset (int) – 0-based byte offset to start reading from.
limit (int | None) – Maximum number of bytes to read (None means read to end).

Returns:

Tuple of (text content, metadata dict) where metadata has total_bytes, returned_bytes, truncated keys.

Raises:

FileNotFoundError – If file doesn’t exist.
UnicodeDecodeError – If the byte range cannot be decoded as UTF-8.

Return type:

tuple[str, dict[str, object]]

read_lines(path, *, start=None, end=None, head=None, tail=None)[source]¶

Read lines from a file with slicing support.

Parameters:

path (str) – Relative path to the file.
start (int | None) – 1-based line number to start from (inclusive).
end (int | None) – 1-based line number to end at (inclusive).
head (int | None) – Return only the first N lines.
tail (int | None) – Return only the last N lines.

Returns:

Tuple of (text content, metadata dict) where metadata has total_lines, returned_lines, truncated keys.

Raises:

ValueError – If conflicting params are supplied.
FileNotFoundError – If file doesn’t exist.

Return type:

tuple[str, dict[str, object]]

remove(path)[source]¶

Remove a file.

Parameters:: path (str) – Relative path to the file.
Return type:: None

stat(path)[source]¶

Get file metadata/stat data.

Parameters:: path (str) – Relative path to the file.
Returns:: Dict with type (‘file’|’dir’|’missing’), size_bytes, created_unix, modified_unix, mode.
Return type:: dict[str, object]

write(path, content)[source]¶

Write content to file.

Parameters:

path (str) – Relative path to the file.
content (str) – Content to write.

Return type:

None

ralph.workspace.scope¶

Canonical workspace scope for the active Ralph run.

Provides WorkspaceScope, the frozen dataclass that centralises all workspace-root and allowed-directory decisions made at process startup. Every component that needs to know where files live or which paths an agent may write should read its values from a WorkspaceScope instance rather than calling Path.cwd() directly.

Key API:

resolve_workspace_scope(start) - detect the active workspace from the filesystem. Walks upward from start (default: cwd()) looking for a ralph-workflow.toml config file or a git repo root. Linked worktrees automatically inherit config from the main worktree unless the linked worktree has its own override.
WorkspaceScope - frozen dataclass with root, allowed_roots, local_config_path, and propagated_config_paths. Use scope.resolve_agent_file(filename) to locate .agent/ files with correct inheritance between linked and main worktrees.
WorkspaceScope.for_same_workspace_worker(...) - builds a restricted scope for parallel workers that share a single checkout; the repo root is NOT added to allowed roots, enforcing that workers only write to their declared directories and their own worker namespace.

Config files searched (in order):: ralph-workflow.toml, agents.toml, pipeline.toml, artifacts.toml, mcp.toml (all under .agent/ in the workspace root).

class ralph.workspace.scope.WorkspaceScope(root, allowed_roots=None, *, local_config_path=None, propagated_config_paths=None)[source]¶

Bases: object

Single source of truth for workspace root and config inheritance.

Parameters:

root (Path)
allowed_roots (tuple[Path, ...])
local_config_path (Path)
propagated_config_paths (tuple[Path, ...])

classmethod for_same_workspace_worker(repo_root, allowed_directories, worker_namespace)[source]¶

Build a worker-scoped view of the shared checkout.

The root stays at repo_root (no per-worker root reassignment). Each allowed directory is resolved relative to repo_root. The worker_namespace is always added so the worker can write its own artifacts, logs, and temporary outputs even when allowed_directories is narrow. A ValueError is raised when any entry escapes repo_root via .. or an absolute path.

This method bypasses the standard __init__ to avoid unconditionally adding repo_root to allowed_roots. Same-workspace workers must NOT have the repo root as an allowed root — they are restricted to only their declared edit areas plus their own worker namespace.

Parameters:

repo_root (Path) – Shared repository root (same for all parallel workers).
allowed_directories (tuple[str, ...]) – Relative subpaths the worker may edit.
worker_namespace (Path) – Per-worker scratch directory (always allowed).

Returns:

WorkspaceScope with root=repo_root, allowed_roots restricted to the declared directories plus the worker namespace (repo root is NOT included).

Return type:

WorkspaceScope

has_any_local_agent_override()[source]¶

Return True when the current workspace has any explicit .agent override.

Return type:: bool

resolve_agent_file(filename)[source]¶

Resolve the effective .agent file for this workspace.

Linked worktrees inherit defaults from the main worktree unless the current workspace has an explicit local override for that filename.

Parameters:: filename (str)
Return type:: Path

ralph.workspace.scope.resolve_workspace_scope(start=None)[source]¶

Resolve the active workspace scope.

The workspace root remains the active checkout, but linked worktrees inherit default .agent config from the main checkout unless the linked worktree has an explicit local override file.

Parameters:: start (Path | str | None)
Return type:: WorkspaceScope

ralph.workspace.skip¶

Skip patterns for recursive workspace traversal.

Defines RECURSIVE_SKIP_DIRECTORY_NAMES, the canonical frozenset of directory names that must never be recursed into during workspace file discovery or context-window content gathering. Applying this set keeps scans fast and prevents noise from VCS internals, build caches, and vendored package trees.

Currently skipped: .git, .hg, .mypy_cache, .pytest_cache, .ruff_cache, .svn, .venv, __pycache__, node_modules, target.

Recovery¶

ralph.recovery¶

Pipeline recovery: failure classification, budgets, connectivity, and retry control.

This package coordinates the recovery cycle that runs after a phase fails. It decides whether to retry the phase, escalate, or abort based on failure classification and remaining budget.

Main entry points:

RecoveryController — top-level controller; evaluates a failure and returns a recovery action (retry, fallover, abort). Injected with a FailureClassifier and an AgentBudgetRegistry.
FailureClassifier, ClassifiedFailure, FailureCategory — classify a raw failure string into a category (agent_error, environment, connectivity, ambiguous, …). is_retryable_without_budget() identifies failures that bypass the budget counter.
AgentBudgetRegistry, FailureBudget, BudgetState, seed_budget_registry — per-agent retry budgets; prevent infinite retry loops.
ConnectivityMonitor, ConnectivityState — background connectivity probe that signals the runner to pause when the host loses network access.
CycleCap — enforces the pipeline-level cycle_cap limit from recovery policy.
FailureEvent, FailureEventBus, FalloverEvent — event types emitted when the recovery controller fires; consumed by the display and logging subsystems.
compute_backoff_ms — computes the exponential backoff delay for the next retry.

ralph.recovery.budget¶

Failure budget tracking per agent in the pipeline.

class ralph.recovery.budget.AgentBudgetRegistry(budgets=None)[source]¶

Bases: object

Registry mapping (phase, agent_name) -> BudgetState.

Immutable-value-returning: debit/reset return new registry instances.

Parameters:: budgets (dict[tuple[str, str], BudgetState] | None)

debit(phase, agent, failure)[source]¶

Return a new registry with the failure debited for (phase, agent).

Parameters:

phase (str)
agent (str)
failure (ClassifiedFailure)

Return type:

AgentBudgetRegistry

is_exhausted(phase, agent)[source]¶

Check if the budget for (phase, agent) is exhausted.

Parameters:

phase (str)
agent (str)

Return type:

bool

items()[source]¶

Iterate over ((phase, agent), state) pairs without exposing the internal dict.

Return type:: Iterable[tuple[tuple[str, str], BudgetState]]

reset(phase, agent)[source]¶

Return a new registry with the budget for (phase, agent) reset.

Parameters:

phase (str)
agent (str)

Return type:

set_budget(phase, agent, max_retries)[source]¶

Return a new registry with this budget initialized.

Parameters:

phase (str)
agent (str)
max_retries (int)

Return type:

class ralph.recovery.budget.BudgetState(max_retries, consumed=0, failures=<factory>)[source]¶

Bases: object

Immutable budget state for a single (phase, agent) pair.

Parameters:

max_retries (int)
consumed (int)
failures (tuple[ClassifiedFailure, ...])

class ralph.recovery.budget.FailureBudget(state)[source]¶

Bases: object

Per-agent failure budget wrapper.

Parameters:: state (BudgetState)

debit(failure)[source]¶

Return a new budget with the failure counted (only if it counts).

Parameters:: failure (ClassifiedFailure)
Return type:: FailureBudget

reset()[source]¶

Return a fresh budget with the same max_retries.

Return type:: FailureBudget

ralph.recovery.budget.seed_budget_registry(bundle)[source]¶

Seed the budget registry from policy bundle configuration.

Parameters:: bundle (PolicyBundle)
Return type:: AgentBudgetRegistry

ralph.recovery.classifier¶

Failure classification: categorize exceptions for intelligent attribution.

class ralph.recovery.classifier.ClassifiedFailure(category, reason, attributed_agent, attributed_phase, counts_against_budget, original_exception, raw_message, reset_session=False)[source]¶

Bases: object

A failure with its category, attribution, and budget-counting decision.

Parameters:

category (FailureCategory)
reason (str)
attributed_agent (str | None)
attributed_phase (str)
counts_against_budget (bool)
original_exception (BaseException | None)
raw_message (str)
reset_session (bool)

class ralph.recovery.classifier.FailureCategory(*values)[source]¶

Bases: StrEnum

Categories of pipeline failures for attribution and routing.

class ralph.recovery.classifier.FailureClassifier[source]¶

Bases: object

Classify failures into categories for intelligent recovery routing.

This is a pure, stateless classifier. All classification rules are encapsulated here so new failure modes are added once, not at call sites.

classify(exc, *, phase, agent)[source]¶

Classify a failure and return a ClassifiedFailure.

Parameters:

exc (BaseException | str)
phase (str)
agent (str | None)

Return type:

ClassifiedFailure

class ralph.recovery.classifier.FailureContext(phase, agent=None, retry_in_session=False, classified_failure=None)[source]¶

Bases: object

Context for a failure event passed to RecoveryController.handle.

Parameters:

phase (str)
agent (str | None)
retry_in_session (bool)
classified_failure (ClassifiedFailure | None)

ralph.recovery.classifier.is_missing_artifact_message(raw_message)[source]¶

Return True if the message indicates a missing required artifact.

Parameters:: raw_message (str)
Return type:: bool

ralph.recovery.classifier.is_retryable_without_budget(failure)[source]¶

Return True if this failure should retry without debiting the agent budget.

Environmental, artifact-validation, and ambiguous failures retry without counting. Agent and user_config failures consume budget.

Parameters:: failure (ClassifiedFailure)
Return type:: bool

ralph.recovery.connectivity¶

Proactive connectivity detection with auto-resume.

class ralph.recovery.connectivity.ConnectivityEvent(state, since, reason)[source]¶

Bases: object

A snapshot of a connectivity state transition.

Parameters:

state (ConnectivityState)
since (datetime)
reason (str)

class ralph.recovery.connectivity.ConnectivityMonitor(*, probe_targets=[('1.1.1.1', 53), ('8.8.8.8', 53)], probe_interval_s=10.0, probe_timeout_s=2.0, probe=None)[source]¶

Bases: object

Proactively detect connectivity loss and surface state transitions.

All timing and network I/O is injectable so tests run deterministically without real sockets.

Parameters:

probe_targets (list[tuple[str, int]])
probe_interval_s (float)
probe_timeout_s (float)
probe (ProbeCallable | None)

add_listener(cb)[source]¶

Parameters:: cb (Callable[[ConnectivityEvent], None])
Return type:: Callable[[], None]

async start()[source]¶

Start the background connectivity probe loop.

Return type:: None

async stop()[source]¶

Stop the background probe loop and unblock any waiters.

Return type:: None

async wait_online()[source]¶

Suspend until connectivity is restored (or monitor is stopped).

Return type:: None

class ralph.recovery.connectivity.ConnectivityState(*values)[source]¶

Bases: StrEnum

Enumeration of observed network connectivity states.

ralph.recovery.controller¶

RecoveryController: single owner of failure classification, budget, and fallover.

class ralph.recovery.controller.RecoveryController(*, options=None)[source]¶

Bases: object

Single conceptual owner of recovery logic.

Handles classification, budget debiting, chain fallover, and cycle cap. Delegates nothing to the reducer’s internal retry counter when active.

Parameters:: options (RecoveryControllerOptions | None)

handle(state, raw_failure, context)[source]¶

Classify a failure and compute the recovery transition.

Parameters:

state (PipelineState) – Current pipeline state.
raw_failure (BaseException | str) – The raw exception or string error message.
context (FailureContext) – Phase/agent context and optional pre-classified failure.

Returns:

Tuple of (new_state, effects, failure_event).

Return type:

tuple[PipelineState, list[Effect], FailureEvent]

reset_backoff(phase, agent)[source]¶

Reset backoff counter for a phase/agent after successful invocation.

Parameters:

phase (str)
agent (str | None)

Return type:

None

snapshot()[source]¶

Return a runtime observability snapshot of recovery state.

Return type:: dict[str, object]

class ralph.recovery.controller.RecoveryControllerOptions(cycle_cap=200, classifier=None, event_bus=None, budget_registry=None, policy_bundle=None, backoff_attempts=None, technical_retry_cap=10)[source]¶

Bases: object

Options for constructing a RecoveryController.

Parameters:

cycle_cap (int)
classifier (FailureClassifier | None)
event_bus (FailureEventBus | None)
budget_registry (AgentBudgetRegistry | None)
policy_bundle (PolicyBundle | None)
backoff_attempts (dict[str, int] | None)
technical_retry_cap (int)

ralph.recovery.controller.compute_backoff_ms(base_ms, attempt, max_ms=30000)[source]¶

Compute exponential backoff delay with cap.

Parameters:

base_ms (int) – Base delay in milliseconds.
attempt (int) – Current retry attempt (0-indexed).
max_ms (int) – Maximum delay cap in milliseconds.

Returns:

Delay in milliseconds, capped at max_ms.

Return type:

int

ralph.recovery.cycle_cap¶

Recovery cycle cap: bounded cap on total recovery cycles.

class ralph.recovery.cycle_cap.CycleCap(cap)[source]¶

Bases: object

Tracks and enforces the maximum number of recovery cycles.

A recovery cycle increments when the entire agent chain for a phase is exhausted. The cap prevents a persistently-failing handler from looping silently forever.

Parameters:: cap (int)

exit_reason(count, last_category, last_reason)[source]¶

Build a descriptive exit reason for when the cap is exceeded.

Parameters:

count (int)
last_category (str)
last_reason (str)

Return type:

str

is_exceeded(count)[source]¶

Return True if count >= cap.

Parameters:: count (int)
Return type:: bool

ralph.recovery.events¶

Structured failure events and event bus for recovery observability.

class ralph.recovery.events.FailureEvent(timestamp, phase, agent, category, reason, counted_against_budget, chain_capacity_remaining, recovery_cycle, retry_delay_ms=0)[source]¶

Bases: object

Structured failure event emitted for every classified failure.

Parameters:

timestamp (datetime)
phase (str)
agent (str | None)
category (str)
reason (str)
counted_against_budget (bool)
chain_capacity_remaining (int)
recovery_cycle (int)
retry_delay_ms (int)

class ralph.recovery.events.FailureEventBus[source]¶

Bases: object

Simple publish/subscribe bus for failure and fallover events.

subscribe(cb)[source]¶

Parameters:: cb (Callable[[FailureEvent | FalloverEvent], None])
Return type:: Callable[[], None]

class ralph.recovery.events.FalloverEvent(timestamp, phase, from_agent, to_agent, reason)[source]¶

Bases: object

Emitted when an agent is exhausted and the chain falls over to the next.

Parameters:

timestamp (datetime)
phase (str)
from_agent (str)
to_agent (str)
reason (str)

ralph.recovery.testing¶

Test helpers for recovery package: fake monitors and fakes for black-box tests.

class ralph.recovery.testing.FakeConnectivityMonitor(initial_state=ConnectivityState.ONLINE)[source]¶

Bases: object

Deterministic connectivity monitor for tests.

Allows injecting state transitions without real network probes.

Parameters:: initial_state (ConnectivityState)

go_offline(reason='test offline')[source]¶

Simulate going offline.

Parameters:: reason (str)
Return type:: None

go_online(reason='test online')[source]¶

Simulate coming back online.

Parameters:: reason (str)
Return type:: None

ralph.recovery.agent_budget_registry¶

Registry mapping (phase, agent_name) to budget state.

class ralph.recovery.agent_budget_registry.AgentBudgetRegistry(budgets=None)[source]¶

Bases: object

Registry mapping (phase, agent_name) -> BudgetState.

Immutable-value-returning: debit/reset return new registry instances.

Parameters:: budgets (dict[tuple[str, str], BudgetState] | None)

debit(phase, agent, failure)[source]¶

Return a new registry with the failure debited for (phase, agent).

Parameters:

phase (str)
agent (str)
failure (ClassifiedFailure)

Return type:

AgentBudgetRegistry

is_exhausted(phase, agent)[source]¶

Check if the budget for (phase, agent) is exhausted.

Parameters:

phase (str)
agent (str)

Return type:

bool

items()[source]¶

Iterate over ((phase, agent), state) pairs without exposing the internal dict.

Return type:: Iterable[tuple[tuple[str, str], BudgetState]]

reset(phase, agent)[source]¶

Return a new registry with the budget for (phase, agent) reset.

Parameters:

phase (str)
agent (str)

Return type:

set_budget(phase, agent, max_retries)[source]¶

Return a new registry with this budget initialized.

Parameters:

phase (str)
agent (str)
max_retries (int)

Return type: