ralph-workflow 0.8.0__py3-none-any.whl

ralph/__init__.py

@@ -0,0 +1,18 @@
+"""Top-level package for Ralph Workflow.
+
+The public Python package is intentionally small at the root: it exposes version
+metadata and points users toward the major subpackages that make up the system.
+
+Useful pydoc entry points:
+
+- ``ralph.cli`` for the Typer CLI application
+- ``ralph.config`` for configuration models and loading
+- ``ralph.pipeline`` for orchestration state and reducer/orchestrator logic
+- ``ralph.phases`` for phase dispatch
+- ``ralph.mcp`` for the MCP bridge and standalone server helpers
+- ``ralph.git`` for GitPython-backed repository operations
+- ``ralph.workspace`` for filesystem abstractions used by production code and tests
+"""
+
+__version__ = "0.8.0"
+__all__ = ["__version__"]

ralph/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m ralph`."""
+
+from ralph.cli.main import app
+
+if __name__ == "__main__":
+    app()

ralph/agents/__init__.py

@@ -0,0 +1,15 @@
+"""Public agent-management exports.
+
+This package exposes the small set of agent abstractions most callers need:
+registry lookup, chain composition, and process invocation.
+"""
+
+from ralph.agents.chain import AgentChain
+from ralph.agents.invoke import invoke_agent
+from ralph.agents.registry import AgentRegistry
+
+__all__ = [
+    "AgentChain",
+    "AgentRegistry",
+    "invoke_agent",
+]

ralph/agents/activity.py

@@ -0,0 +1,28 @@
+"""Watchdog-relevant activity signals emitted by agent transports."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class AgentActivityKind(StrEnum):
+    """Kinds of agent activity that can reset the idle watchdog."""
+
+    OUTPUT_LINE = "output_line"
+    STREAM_DELTA = "stream_delta"
+    TOOL_USE = "tool_use"
+    TOOL_RESULT = "tool_result"
+    LIFECYCLE = "lifecycle"
+    CHILD_PROCESS = "child_process"
+    CHILD_HEARTBEAT = "child_heartbeat"
+    CHILD_PROGRESS = "child_progress"
+    CHILD_TERMINAL_ACK = "child_terminal_ack"
+
+
+@dataclass(frozen=True, slots=True)
+class AgentActivitySignal:
+    """Small transport-neutral signal consumed by timeout control flow."""
+
+    kind: AgentActivityKind
+    raw: str = ""

ralph/agents/availability.py

@@ -0,0 +1,62 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import shutil
+from typing import Literal, Protocol, runtime_checkable
+
+AgentStatus = Literal["available", "missing_on_path", "no_cmd"]
+
+
+class _AgentEntry(Protocol):
+    """Minimal agent config interface for availability checks."""
+
+    cmd: str
+    display_name: str | None
+
+
+@runtime_checkable
+class HasListAgents(Protocol):
+    """Protocol for agent registries used in availability checks."""
+
+    def list_agents(self) -> list[str]:
+        ...
+
+    def get(self, name: str) -> _AgentEntry | None:
+        ...
+
+
+def check_agent_availability(
+    registry: HasListAgents,
+) -> list[tuple[str, AgentStatus]]:
+    """Check which agents are available on PATH.
+
+    Args:
+        registry: 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.
+    """
+    results: list[tuple[str, AgentStatus]] = []
+    for name in registry.list_agents():
+        agent = registry.get(name)
+        if agent is None:
+            continue
+        cmd = agent.cmd
+        if not cmd:
+            results.append((name, "no_cmd"))
+            continue
+        first_word = cmd.split(maxsplit=1)[0]
+        status: AgentStatus = (
+            "available" if shutil.which(first_word) is not None else "missing_on_path"
+        )
+        results.append((name, status))
+    return results

ralph/agents/chain.py

@@ -0,0 +1,296 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from ralph.policy.models import AgentChainConfig, AgentDrainConfig, AgentsPolicy, DrainName
+
+if TYPE_CHECKING:
+    from ralph.config.models import UnifiedConfig
+
+
+class DrainNotBoundError(Exception):
+    """Raised when a drain has no explicit chain binding.
+
+    Attributes:
+        drain: The unbound drain name.
+        available_drains: Names of all bound drains.
+    """
+
+    def __init__(self, drain: str, available_drains: set[str]) -> None:
+        self.drain = drain
+        self.available_drains = available_drains
+        available = sorted(available_drains)
+        msg = (
+            f"Drain '{drain}' is not bound to any agent chain in agents.toml. "
+            f"Available drains: {available}. "
+            f"Add a binding for '{drain}' in agent_drains or use a bound drain."
+        )
+        super().__init__(msg)
+
+
+class UnknownAgentError(Exception):
+    """Raised when an agent name is not found in the registry.
+
+    Attributes:
+        agent_name: The unknown agent name.
+    """
+
+    def __init__(self, agent_name: str) -> None:
+        self.agent_name = agent_name
+        msg = f"Unknown agent: '{agent_name}'. Register the agent in the configuration."
+        super().__init__(msg)
+
+
+class AgentChain:
+    """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
+
+    Attributes:
+        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.
+    """
+
+    def __init__(
+        self,
+        agents: list[str],
+        max_retries: int = 3,
+        retry_delay_ms: int = 1000,
+        backoff_multiplier: float = 2.0,
+        max_backoff_ms: int = 60000,
+    ) -> None:
+        """Initialize agent chain.
+
+        Args:
+            agents: List of agent names in fallback order.
+            max_retries: Maximum retries per agent before fallback.
+            retry_delay_ms: Base delay between retries in milliseconds.
+            backoff_multiplier: Multiplier for exponential backoff.
+            max_backoff_ms: Maximum backoff delay in milliseconds.
+        """
+        self.agents = agents
+        self.current_index = 0
+        self.retries = 0
+        self.max_retries = max_retries
+        self.retry_delay_ms = retry_delay_ms
+        self.backoff_multiplier = backoff_multiplier
+        self.max_backoff_ms = max_backoff_ms
+
+    @property
+    def current_agent(self) -> str | None:
+        """Get the current agent name.
+
+        Returns:
+            Agent name or None if chain is exhausted.
+        """
+        if not self.agents or self.current_index >= len(self.agents):
+            return None
+        return self.agents[self.current_index]
+
+    @property
+    def is_exhausted(self) -> bool:
+        """Check if all agents in chain are exhausted.
+
+        Returns:
+            True if no agents remain.
+        """
+        return self.current_agent is None
+
+    def can_retry(self) -> bool:
+        """Check if current agent can be retried.
+
+        Returns:
+            True if retries remain for current agent.
+        """
+        return self.retries < self.max_retries
+
+    def advance(self) -> bool:
+        """Advance to the next agent in the chain.
+
+        Returns:
+            True if advanced successfully, False if chain exhausted.
+        """
+        if self.current_index + 1 < len(self.agents):
+            self.current_index += 1
+            self.retries = 0
+            logger.debug("Advanced to next agent: {}", self.current_agent)
+            return True
+        logger.debug("Agent chain exhausted")
+        return False
+
+    def record_retry(self) -> None:
+        """Record a retry attempt for current agent."""
+        self.retries += 1
+        logger.debug(
+            "Retry {} of {} for agent {}",
+            self.retries,
+            self.max_retries,
+            self.current_agent,
+        )
+
+    def calculate_backoff(self) -> float:
+        """Calculate backoff delay in seconds.
+
+        Returns:
+            Backoff delay in seconds.
+        """
+        delay = self.retry_delay_ms * (self.backoff_multiplier**self.retries)
+        return min(delay, self.max_backoff_ms) / 1000.0
+
+    def wait_backoff(self) -> None:
+        """Wait for the backoff period."""
+        backoff = self.calculate_backoff()
+        logger.debug("Backing off for {:.2f} seconds", backoff)
+        time.sleep(backoff)
+
+
+class ChainManager:
+    """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.
+
+    Attributes:
+        agents_policy: The agents policy containing chains and drain bindings.
+    """
+
+    def __init__(self, agents_policy: AgentsPolicy) -> None:
+        """Initialize ChainManager with an AgentsPolicy.
+
+        Args:
+            agents_policy: Validated agents policy with chain and drain definitions.
+        """
+        self._policy = agents_policy
+
+    @classmethod
+    def from_config(cls, config: UnifiedConfig) -> ChainManager:
+        """Create ChainManager from a legacy UnifiedConfig.
+
+        This is a compatibility shim that converts the old UnifiedConfig
+        format to the new AgentsPolicy format.
+
+        Args:
+            config: Legacy unified configuration.
+
+        Returns:
+            ChainManager instance.
+        """
+        agent_chains: dict[str, AgentChainConfig] = {}
+        for name, agents in config.agent_chains.items():
+            agent_chains[name] = AgentChainConfig(agents=agents)
+
+        agent_drains: dict[DrainName, AgentDrainConfig] = {}
+        for drain, chain in config.agent_drains.items():
+            agent_drains[drain] = AgentDrainConfig(chain=chain)
+
+        policy = AgentsPolicy(
+            agent_chains=agent_chains,
+            agent_drains=agent_drains,
+        )
+        return cls(policy)
+
+    def chain_for_drain(self, drain: DrainName) -> AgentChainConfig:
+        """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.
+
+        Args:
+            drain: Drain name to look up.
+
+        Returns:
+            AgentChainConfig for the bound chain.
+
+        Raises:
+            DrainNotBoundError: If the drain is not explicitly bound.
+        """
+        binding = self._policy.agent_drains.get(drain)
+        if binding is None:
+            raise DrainNotBoundError(
+                drain=drain,
+                available_drains=set(self._policy.agent_drains.keys()),
+            )
+
+        chain = self._policy.agent_chains.get(binding.chain)
+        if chain is None:
+            msg = (
+                f"Drain '{drain}' references chain '{binding.chain}' "
+                f"which is not defined in agent_chains"
+            )
+            raise ValueError(msg)
+
+        return chain
+
+    def chain_config_for_drain(self, drain: DrainName) -> AgentChainConfig:
+        """Alias for chain_for_drain for clarity."""
+        return self.chain_for_drain(drain)
+
+    def validate(self) -> list[str]:
+        """Validate the policy for internal consistency.
+
+        Returns:
+            List of validation error messages (empty if valid).
+        """
+        errors: list[str] = []
+
+        for drain, binding in self._policy.agent_drains.items():
+            if binding.chain not in self._policy.agent_chains:
+                errors.append(f"Drain '{drain}' references unknown chain '{binding.chain}'")
+
+        for name, chain in self._policy.agent_chains.items():
+            if not chain.agents:
+                errors.append(f"Chain '{name}' has no agents")
+
+        return errors
+
+
+def create_chain_from_config(
+    config: UnifiedConfig,
+    chain_name: str,
+) -> AgentChain | None:
+    """Create an AgentChain from UnifiedConfig.
+
+    Args:
+        config: Unified configuration.
+        chain_name: Name of the chain in agent_chains.
+
+    Returns:
+        AgentChain instance or None if chain not found.
+    """
+    agent_names = config.agent_chains.get(chain_name)
+    if not agent_names:
+        return None
+
+    return AgentChain(
+        agents=agent_names,
+        max_retries=config.general.max_retries,
+        retry_delay_ms=config.general.retry_delay_ms,
+        backoff_multiplier=config.general.backoff_multiplier,
+        max_backoff_ms=config.general.max_backoff_ms,
+    )

ralph/agents/completion_signals.py

@@ -0,0 +1,135 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ralph.phases.required_artifacts import RequiredArtifact
+
+_EXPLICIT_COMPLETION_MARKER = "Task declared complete:"
+
+
+@dataclass(frozen=True)
+class CompletionSignals:
+    """Signals that indicate whether an agent run actually completed its work.
+
+    Attributes:
+        explicit_complete: True when the agent called the declare_complete MCP
+            tool successfully (independent of artifact presence).
+        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.
+        artifact_types: Tuple of artifact type names found.
+        terminal_ack_seen: True when a child_terminal lifecycle ACK was received
+            from the OpenCode transport.
+        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.
+    """
+
+    explicit_complete: bool
+    required_artifact_present: bool
+    artifact_types: tuple[str, ...]
+    terminal_ack_seen: bool = False
+    artifact_optional: bool = False
+
+
+def extract_explicit_completion(raw_output: list[str]) -> bool:
+    """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.
+
+    Args:
+        raw_output: Raw NDJSON lines from the agent subprocess stdout.
+
+    Returns:
+        True if the declare_complete marker is found in any output line.
+    """
+    return any(_EXPLICIT_COMPLETION_MARKER in line for line in raw_output)
+
+
+def _artifact_is_schema_valid(artifact_path: Path) -> bool:
+    """Return True when the artifact file exists, parses as JSON, and is a non-empty dict."""
+    if not artifact_path.exists():
+        return False
+    try:
+        content = artifact_path.read_text(encoding="utf-8")
+        parsed = cast("object", json.loads(content))
+        return isinstance(parsed, dict) and len(parsed) > 0
+    except (OSError, json.JSONDecodeError, ValueError):
+        return False
+
+
+def evaluate_completion(
+    workspace: Path,
+    raw_output: list[str] | None = None,
+    *,
+    required_artifact: RequiredArtifact | None = None,
+) -> CompletionSignals:
+    """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.
+
+    Args:
+        workspace: Workspace root path.
+        raw_output: Raw NDJSON lines from agent stdout for explicit-completion detection.
+        required_artifact: Policy-derived artifact metadata.
+
+    Returns:
+        CompletionSignals reflecting current artifact state and explicit completion.
+    """
+    explicit = extract_explicit_completion(raw_output or [])
+    ra = required_artifact
+    if ra is None:
+        return CompletionSignals(
+            explicit_complete=explicit,
+            required_artifact_present=False,
+            artifact_types=(),
+        )
+    artifact_path = workspace / ra.json_path
+    present = _artifact_is_schema_valid(artifact_path)
+    optional = not ra.artifact_required
+    return CompletionSignals(
+        explicit_complete=explicit,
+        required_artifact_present=present,
+        artifact_types=(ra.artifact_type,) if present else (),
+        artifact_optional=optional,
+    )
+
+
+__all__ = [
+    "CompletionSignals",
+    "evaluate_completion",
+    "extract_explicit_completion",
+]