ralphception 0.1.0__py3-none-any.whl

ralphception/__init__.py

@@ -0,0 +1,8 @@
+"""Ralphception package metadata."""
+
+__all__ = ["__version__"]
+
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0"

ralphception/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

ralphception/actor_runtime/__init__.py

@@ -0,0 +1,20 @@
+"""Actor-runtime entrypoints."""
+
+from .intake_actor import IntakeActor
+from .merge_actor import MergeAgent, MergeDecision, WorkerCandidate
+from .orchestrator import ActorOrchestrator
+from .planner_actor import PlannerActor
+from .scheduler_actor import SchedulerActor
+from .worker_actor import WorkerActor, WorkerAssignment
+
+__all__ = [
+    "ActorOrchestrator",
+    "IntakeActor",
+    "MergeAgent",
+    "MergeDecision",
+    "PlannerActor",
+    "SchedulerActor",
+    "WorkerCandidate",
+    "WorkerActor",
+    "WorkerAssignment",
+]

ralphception/actor_runtime/intake_actor.py

@@ -0,0 +1,116 @@
+"""Mission-start intake helpers for the actor runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ralphception.models.mission import MissionPhase, MissionSession
+from ralphception.runtime.frontends import StartupPrompt
+from ralphception.storage.mission_store import MissionStore
+from ralphception.ui.screens.startup import StartupBootstrapController, load_startup_record
+from ralphception.workflow.approvals import read_approval
+
+_SPEC_ARTIFACT_PATH = Path(".ralphception/specs/mission-spec.md")
+
+
+class IntakeActor:
+    """Owns the initial mission brief capture and spec-approval phase state."""
+
+    def __init__(self, repo_root: Path) -> None:
+        self.repo_root = repo_root
+        self._store = MissionStore(repo_root)
+        self._startup = StartupBootstrapController(repo_root)
+
+    def load_session(self) -> MissionSession | None:
+        session = self._store.read_session()
+        if session is None:
+            startup_record = load_startup_record(self.repo_root)
+            if startup_record is None:
+                return None
+            session = MissionSession(
+                mission_id=startup_record.outer_run_id,
+                repo_root=str(self.repo_root),
+                phase=self._phase_from_workspace(),
+                approved_spec_version=1 if self._has_spec_approval() else None,
+            )
+            self._store.write_session(session)
+            return session
+
+        desired_phase = self._phase_from_workspace()
+        approved_spec_version = 1 if self._has_spec_approval() else None
+        if session.phase == desired_phase and session.approved_spec_version == approved_spec_version:
+            return session
+        updated = session.model_copy(
+            update={
+                "phase": desired_phase,
+                "approved_spec_version": approved_spec_version,
+            }
+        )
+        self._store.write_session(updated)
+        return updated
+
+    def next_prompt(self, session: MissionSession | None) -> StartupPrompt:
+        del session
+        return StartupPrompt(
+            repo_root=self.repo_root,
+            message=(
+                "Socratic intake\n\n"
+                "Describe the mission for this workspace and any source repositories Ralphception "
+                "should inspect before drafting the spec."
+            ),
+        )
+
+    def apply_answer(self, *, seed_prompt: str, source_repos: tuple[str, ...]) -> MissionSession:
+        record = self._startup.start_first_run(
+            seed_prompt=seed_prompt,
+            source_repos=source_repos,
+        )
+        session = MissionSession(
+            mission_id=record.outer_run_id,
+            repo_root=str(self.repo_root),
+            phase="intake",
+            approved_spec_version=None,
+        )
+        self._store.write_session(session)
+        return session
+
+    def mark_ready_for_spec_review(self) -> MissionSession:
+        session = self._require_session()
+        updated = session.model_copy(
+            update={
+                "phase": "spec_review",
+                "approved_spec_version": None,
+            }
+        )
+        self._store.write_session(updated)
+        return updated
+
+    def approve_spec(self, *, artifact_version: int = 1) -> MissionSession:
+        session = self._require_session()
+        updated = session.model_copy(
+            update={
+                "phase": "planning",
+                "approved_spec_version": artifact_version,
+            }
+        )
+        self._store.write_session(updated)
+        return updated
+
+    def _require_session(self) -> MissionSession:
+        session = self.load_session()
+        if session is None:
+            raise RuntimeError("mission session is not initialized")
+        return session
+
+    def _phase_from_workspace(self) -> MissionPhase:
+        if self._has_spec_approval():
+            return "planning"
+        if (self.repo_root / _SPEC_ARTIFACT_PATH).exists():
+            return "spec_review"
+        return "intake"
+
+    def _has_spec_approval(self) -> bool:
+        approval_path = self.repo_root / ".ralphception" / "approvals" / "approval-spec-1.json"
+        if not approval_path.exists():
+            return False
+        return read_approval(self.repo_root, approval_id="approval-spec-1") is not None

ralphception/actor_runtime/merge_actor.py

@@ -0,0 +1,88 @@
+"""Merge-agent candidate selection for commit intents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from ralphception.git.merge import normalize_final_commit_message
+from ralphception.models.artifacts import DurableModel
+from ralphception.models.commit_intents import CommitIntent
+from ralphception.storage.commit_intents import update_commit_intent_winner
+
+
+class WorkerCandidate(DurableModel):
+    candidate_id: str
+    commit_intent_id: str
+    summary: str
+    touched_paths: list[str] = Field(default_factory=list)
+    verification_passed: bool = True
+
+    @field_validator("candidate_id", "commit_intent_id", "summary")
+    @classmethod
+    def _validate_non_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("worker candidate fields must not be blank")
+        return value
+
+
+class MergeDecision(DurableModel):
+    intent_id: str
+    selected_candidate_id: str
+    rejected_candidate_ids: list[str]
+    commit_message: str
+    rationale: str
+
+    @field_validator("intent_id", "selected_candidate_id", "commit_message", "rationale")
+    @classmethod
+    def _validate_non_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("merge decision fields must not be blank")
+        return value
+
+
+class MergeAgent:
+    """Select the strongest candidate for a commit intent and record the result."""
+
+    def __init__(self, *, repo_root: Path | None = None) -> None:
+        self.repo_root = repo_root
+
+    def choose_candidate(self, intent: CommitIntent, candidates: list[WorkerCandidate]) -> MergeDecision:
+        matching = [candidate for candidate in candidates if candidate.commit_intent_id == intent.intent_id]
+        if not matching:
+            raise ValueError(f"no candidates matched commit intent {intent.intent_id!r}")
+
+        ordered = sorted(
+            matching,
+            key=lambda candidate: (
+                candidate.verification_passed,
+                len(candidate.touched_paths),
+                candidate.candidate_id,
+            ),
+        )
+        selected = ordered[-1]
+        rejected = [candidate.candidate_id for candidate in ordered[:-1]]
+        rationale = (
+            f"selected {selected.candidate_id} for {intent.intent_id} based on verification state "
+            f"and touched-path coverage"
+        )
+        return MergeDecision(
+            intent_id=intent.intent_id,
+            selected_candidate_id=selected.candidate_id,
+            rejected_candidate_ids=rejected,
+            commit_message=normalize_final_commit_message(intent.message),
+            rationale=rationale,
+        )
+
+    def record_decision(self, intent: CommitIntent, decision: MergeDecision) -> CommitIntent:
+        if self.repo_root is None:
+            raise RuntimeError("repo_root is required to record merge decisions")
+        return update_commit_intent_winner(
+            self.repo_root,
+            intent_id=intent.intent_id,
+            candidate_id=decision.selected_candidate_id,
+        )
+
+    def land_intent(self, decision: MergeDecision) -> str:
+        return normalize_final_commit_message(decision.commit_message)

ralphception/actor_runtime/orchestrator.py

@@ -0,0 +1,110 @@
+"""Actor-runtime orchestrator for intake and spec approval."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ralphception.actor_runtime.intake_actor import IntakeActor
+from ralphception.headless import HeadlessMissionSupervisor, HeadlessRunResult
+from ralphception.runtime.frontends import FrontendEvent, RuntimeFrontend
+
+
+class ActorOrchestrator:
+    """Shared orchestrator fronting the legacy downstream executor."""
+
+    def __init__(
+        self,
+        *,
+        repo_root: Path,
+        primary_repo_root: Path,
+        seed_prompt: str | None,
+        source_repos: tuple[str, ...],
+        approve_all: bool,
+        approver: str,
+        session_manager_factory,
+    ) -> None:
+        self.repo_root = repo_root
+        self.primary_repo_root = primary_repo_root
+        self.seed_prompt = seed_prompt
+        self.source_repos = source_repos
+        self.approve_all = approve_all
+        self.approver = approver
+        self.session_manager_factory = session_manager_factory
+        self.intake_actor = IntakeActor(repo_root)
+        self.actions: list[str] = []
+
+    def run_until_blocked(self, *, frontend: RuntimeFrontend | None = None) -> HeadlessRunResult:
+        session = self.intake_actor.load_session()
+        if session is None:
+            self._emit(frontend, "Socratic intake")
+            if self.seed_prompt is None or not self.seed_prompt.strip():
+                if frontend is None:
+                    return HeadlessRunResult(
+                        mode="startup",
+                        actions=(),
+                        authoritative_repo_root=str(self.repo_root),
+                    )
+                decision = frontend.prompt_startup(self.intake_actor.next_prompt(None))
+                self.seed_prompt = decision.seed_prompt
+                self.source_repos = decision.source_repos
+            session = self.intake_actor.apply_answer(
+                seed_prompt=self.seed_prompt or "",
+                source_repos=self.source_repos,
+            )
+            self._emit(frontend, f"Bootstrapped {session.mission_id}")
+        elif session.phase in {"intake", "spec_review"}:
+            self._emit(frontend, "Socratic intake")
+
+        if session.phase in {"intake", "spec_review"}:
+            review_result = self._run_spec_gate(frontend=frontend)
+            if review_result is not None:
+                return self._with_accumulated_actions(review_result)
+            announce_resume = False
+        else:
+            announce_resume = True
+
+        downstream = self._build_downstream_supervisor(
+            approve_all=True,
+            announce_resume=announce_resume,
+        )
+        return self._with_accumulated_actions(downstream.run(frontend=frontend))
+
+    def _run_spec_gate(self, *, frontend: RuntimeFrontend | None) -> HeadlessRunResult | None:
+        supervisor = self._build_downstream_supervisor(approve_all=self.approve_all)
+        supervisor._frontend = frontend
+        supervisor._announce_stage("spec")
+        review_result = supervisor._run_spec_stage(frontend=frontend)
+        self.actions.extend(supervisor.actions)
+        if review_result is not None:
+            self.intake_actor.mark_ready_for_spec_review()
+            return review_result
+        self.intake_actor.approve_spec(artifact_version=1)
+        self._emit(frontend, "Spec approved. Proceeding autonomously.")
+        return None
+
+    def _build_downstream_supervisor(
+        self,
+        *,
+        approve_all: bool,
+        announce_resume: bool = True,
+    ) -> HeadlessMissionSupervisor:
+        return HeadlessMissionSupervisor(
+            repo_root=self.repo_root,
+            primary_repo_root=self.primary_repo_root,
+            seed_prompt=self.seed_prompt,
+            source_repos=self.source_repos,
+            approve_all=approve_all,
+            approver=self.approver,
+            session_manager_factory=self.session_manager_factory,
+            announce_resume=announce_resume,
+        )
+
+    def _emit(self, frontend: RuntimeFrontend | None, message: str) -> None:
+        if frontend is None:
+            return
+        frontend.emit_event(FrontendEvent(message=message))
+
+    def _with_accumulated_actions(self, result: HeadlessRunResult) -> HeadlessRunResult:
+        if not self.actions:
+            return result
+        return result.model_copy(update={"actions": (*self.actions, *result.actions)})

ralphception/actor_runtime/planner_actor.py

@@ -0,0 +1,47 @@
+"""Planner actor for durable plan outputs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ralphception.headless import _load_plan_contract, _preferred_artifact_path
+from ralphception.models.mission import PlannerOutput
+from ralphception.storage.mission_store import MissionStore
+
+
+class PlannerActor:
+    """Persist todo and commit-intent outputs derived from the approved plan contract."""
+
+    def __init__(self, *, repo_root: Path, store: MissionStore | None = None) -> None:
+        self.repo_root = repo_root
+        self.store = store or MissionStore(repo_root)
+
+    def plan(self, *, approved_spec_path: Path) -> PlannerOutput:
+        if not approved_spec_path.exists():
+            fallback_spec_path = _preferred_artifact_path(
+                approved_spec_path.parent,
+                preferred_name=approved_spec_path.name,
+            )
+            if not fallback_spec_path.exists():
+                raise FileNotFoundError(f"approved spec is missing: {approved_spec_path}")
+            approved_spec_path = fallback_spec_path
+
+        plans_dir = self.repo_root / ".ralphception" / "plans"
+        plan_markdown_path = _preferred_artifact_path(plans_dir, preferred_name="mission-plan.md")
+        plan_json_path = plans_dir / "mission-plan.json"
+        contract = _load_plan_contract(
+            plan_json_path,
+            default_goal=f"Implement {approved_spec_path.stem}.",
+        )
+
+        self.store.write_todos(contract.todos)
+        self.store.write_commit_intents(contract.commit_intents)
+        output = PlannerOutput(
+            plan_markdown_path=str(plan_markdown_path.relative_to(self.repo_root)),
+            plan_json_path=str(plan_json_path.relative_to(self.repo_root)),
+            todo_ids=[todo.todo_id for todo in contract.todos],
+            commit_intent_ids=[intent.intent_id for intent in contract.commit_intents],
+            execution_policy=contract.execution_policy,
+        )
+        self.store.write_planner_output(output)
+        return output

ralphception/actor_runtime/scheduler_actor.py

@@ -0,0 +1,65 @@
+"""Scheduler batching logic for ready todo execution."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from ralphception.actor_runtime.worker_actor import WorkerAssignment
+from ralphception.models.mission import ExecutionPolicy
+from ralphception.models.todos import TodoNode
+
+
+class SchedulerActor:
+    """Plans worker assignments for ready todo batches."""
+
+    def __init__(self, *, max_parallel_children: int) -> None:
+        self.max_parallel_children = max_parallel_children
+
+    @classmethod
+    def from_execution_policy(cls, policy: ExecutionPolicy) -> "SchedulerActor":
+        return cls(max_parallel_children=policy.max_parallel_children)
+
+    def plan_assignments(
+        self,
+        *,
+        todos: list[TodoNode],
+        active_workers: list[WorkerAssignment],
+    ) -> list[WorkerAssignment]:
+        available_slots = max(0, self.max_parallel_children - len(active_workers))
+        if available_slots == 0:
+            return []
+
+        claimed_todo_ids = {todo_id for worker in active_workers for todo_id in worker.todo_ids}
+        ready_todos = [
+            todo
+            for todo in todos
+            if todo.status == "ready" and todo.todo_id not in claimed_todo_ids
+        ]
+        grouped: dict[tuple[str, str], list[TodoNode]] = defaultdict(list)
+        for todo in ready_todos:
+            grouped[(todo.commit_intent_id, _scope_group(todo.scope_hints))].append(todo)
+
+        assignments: list[WorkerAssignment] = []
+        worker_index = len(active_workers) + 1
+        for key in sorted(grouped):
+            if len(assignments) >= available_slots:
+                break
+            batch = sorted(grouped[key], key=lambda todo: todo.todo_id)
+            assignments.append(
+                WorkerAssignment(
+                    worker_id=f"worker-{worker_index}",
+                    run_id=f"run-worker-{worker_index}",
+                    goal="; ".join(todo.title for todo in batch),
+                    todo_ids=[todo.todo_id for todo in batch],
+                    claimed_commit_intent_ids=sorted({todo.commit_intent_id for todo in batch}),
+                )
+            )
+            worker_index += 1
+        return assignments
+
+
+def _scope_group(scope_hints: list[str]) -> str:
+    if not scope_hints:
+        return ""
+    first_hint = scope_hints[0].strip().replace("\\", "/")
+    return first_hint.split("/", 1)[0] if first_hint else ""

ralphception/actor_runtime/worker_actor.py

@@ -0,0 +1,59 @@
+"""Worker assignment and worktree startup helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator
+
+from ralphception.git.worktrees import WorktreeCoordinator
+from ralphception.models.artifacts import DurableModel
+
+
+class WorkerAssignment(DurableModel):
+    worker_id: str
+    run_id: str
+    goal: str
+    todo_ids: list[str] = Field(min_length=1)
+    claimed_commit_intent_ids: list[str] = Field(min_length=1)
+    worktree_path: str | None = None
+    status: Literal["planned", "running", "completed", "failed"] = "planned"
+
+    @field_validator("worker_id", "run_id", "goal")
+    @classmethod
+    def _validate_non_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("worker assignment fields must not be blank")
+        return value
+
+    @field_validator("todo_ids", "claimed_commit_intent_ids")
+    @classmethod
+    def _validate_non_blank_items(cls, value: list[str]) -> list[str]:
+        if any(not item.strip() for item in value):
+            raise ValueError("worker assignment list fields must not contain blank values")
+        return value
+
+
+class WorkerActor:
+    """Starts worker assignments in git worktrees."""
+
+    def __init__(self, *, repo_root: Path, base_ref: str, target_branch: str) -> None:
+        self.repo_root = repo_root
+        self.base_ref = base_ref
+        self.target_branch = target_branch
+        self.worktrees = WorktreeCoordinator(repo_root=repo_root)
+
+    def start(self, assignment: WorkerAssignment) -> WorkerAssignment:
+        created = self.worktrees.create_child_worktree(
+            run_id=assignment.run_id,
+            base_ref=self.base_ref,
+            target_branch=f"{self.target_branch}-{assignment.run_id}",
+            goal=assignment.goal,
+        )
+        return assignment.model_copy(
+            update={
+                "worktree_path": str(created.worktree_path),
+                "status": "running",
+            }
+        )