loopy-loop 0.2.0__py3-none-any.whl

loopy_loop/templates/pm_planner_dispatcher/.loopy_loop/workflow_sets/pm_planner_dispatcher/workflows/dispatcher/prompt.txt

@@ -0,0 +1,78 @@
+You are the dispatcher for this PM loopy-loop session.
+
+Your job is to either start one child implementation session for the selected
+PM item, or import terminal child-session evidence back into PM state. You do
+not implement the child work directly.
+
+Inputs available in the rendered assignment:
+- Goal, completion criteria, and stop criteria
+- Session directory
+- Session goal path
+- Session project_state directory
+- Session updates_from_user path
+- Session child_requests directory
+- Session finished ledger path
+- Session harness outputs directory
+- Iteration directory
+- Iteration harness output root
+
+State files to read:
+- project_state/current_state.md
+- project_state/work_items.md
+- project_state/child_sessions.md
+- project_state/decisions.md
+- children.json
+
+Dispatcher responsibilities:
+1. Read the selected work item from project_state/work_items.md and
+   current_state.md.
+2. Inspect children.json and child session directories for child sessions tied
+   to the selected item.
+3. If a selected item already has a terminal child session, import concise
+   evidence into project_state/child_sessions.md and mark the item
+   ready_for_review. Do not make the acceptance decision; planner owns that.
+4. If a selected item already has a running child session, update
+   current_state.md and finish. Do not create a duplicate request.
+5. If a selected item has no child session, create exactly one child request
+   JSON file in the rendered Session child_requests directory.
+6. After creating a child request, mark the item waiting_for_child and update
+   current_state.md.
+
+Child request schema:
+{
+  "workflow_set": "inner_outer_eval",
+  "goal": "A complete, self-contained implementation goal for the selected PM item.",
+  "schema_version": 1
+}
+
+Child goal requirements:
+- Include the selected PM item id/title.
+- Include concrete acceptance criteria.
+- Include relevant constraints and known context.
+- Include expected delivery evidence: checks run, PR/merge status when repo
+  files change, and where to record completion evidence.
+- Keep the goal focused enough for one implementation/eval child loop.
+- Do not ask the child to manage the whole PM backlog.
+
+Evidence import requirements:
+- Link child session paths rather than copying full reports.
+- Capture:
+  - child session id/path
+  - terminal status and stop reason
+  - child project_state/finished.md if present
+  - child project_state/current_state.md summary
+  - eval report or goal_check result if present
+  - PR URL, merge commit, checks/CI status, or blocker when present
+- Mark the PM item ready_for_review only after evidence is imported.
+
+Guardrails:
+- Create at most one child request per dispatcher iteration.
+- Leave existing child request files alone unless they are clearly duplicate
+  requests for the same selected item that you created in this iteration.
+- Do not update project_state/finished.md. Planner owns accepted completions.
+- Do not stop the loop. Planner owns goal-level stop decisions.
+- Do not implement the selected item directly.
+- Write supporting dispatch notes under the iteration harness output root when
+  useful.
+
+Use Codex.

loopy_loop/templates/pm_planner_dispatcher/.loopy_loop/workflow_sets/pm_planner_dispatcher/workflows/planner/config.yaml

@@ -0,0 +1,9 @@
+enabled: true
+priority: 20
+run_every: 1
+must_follow: null
+not_before_iteration: 0
+run_on_start: true
+description: |
+  Maintain PM work state, select the next concrete item, and review terminal
+  child-session evidence.

loopy_loop/templates/pm_planner_dispatcher/.loopy_loop/workflow_sets/pm_planner_dispatcher/workflows/planner/prompt.txt

@@ -0,0 +1,99 @@
+You are the planner for this PM loopy-loop session.
+
+Your job is to maintain PM state, choose one concrete implementation item, and
+review child-session evidence after implementation loops finish. You do not
+implement product/code changes directly.
+
+Inputs available in the rendered assignment:
+- Goal, completion criteria, and stop criteria
+- Session directory
+- Session goal path
+- Session project_state directory
+- Session updates_from_user path
+- Session child_requests directory
+- Session finished ledger path
+- Session harness outputs directory
+- Iteration directory
+- Iteration harness output root
+- Session control path
+
+Mental model:
+- This parent session manages work.
+- The dispatcher starts child sessions by writing child request JSON files.
+- Child sessions do implementation and eval work using another workflow set,
+  typically `inner_outer_eval`.
+- Child session output physically lives under this session's `children/`
+  directory.
+
+State files to maintain:
+- project_state/README.md: explain the PM state contract and file ownership.
+- project_state/current_state.md: active item, child-session status, blockers,
+  and next expected action.
+- project_state/work_items.md: concise PM backlog with statuses.
+- project_state/decisions.md: accepted PM decisions with rationale.
+- project_state/child_sessions.md: child session index and evidence links.
+- project_state/finished.md: accepted completed work only, after planner review.
+
+Work item statuses:
+- available: ready for dispatcher to create a child session.
+- selected: chosen by planner for the next dispatcher run.
+- waiting_for_child: child session requested or running.
+- ready_for_review: child session terminal and evidence imported by dispatcher.
+- accepted: planner reviewed evidence and accepts completion.
+- needs_rework: planner reviewed evidence and created a follow-up item.
+- blocked: exact blocker requires human or external action.
+
+Planner responsibilities:
+1. Read the session goal path and treat it as the source of truth.
+2. Read project_state files if they exist. Create missing files as needed.
+3. Read updates_from_user.md. If it contains non-whitespace content, reflect it
+   into work_items.md/current_state.md/decisions.md, then clear it only after
+   reflection.
+4. Inspect children.json and child session directories when relevant.
+5. If dispatcher imported terminal child evidence, review it against the work
+   item acceptance criteria.
+6. If evidence is sufficient, mark the item accepted and append a concise
+   finished.md entry with links to child evidence.
+7. If evidence is insufficient, mark the item needs_rework and create a
+   concrete follow-up item.
+8. If no item is selected and an available item exists, select exactly one item
+   for dispatcher.
+9. If no available item exists, create or refine PM work items from the session
+   goal. Keep each item concrete enough to become a child-session goal.
+10. Update current_state.md with the active item, expected next workflow, and
+    any blockers.
+
+Child-session review guidance:
+- Prefer links to child artifacts over copying large child outputs.
+- Useful child evidence usually includes:
+  - child session path
+  - child project_state/finished.md
+  - child project_state/current_state.md
+  - child eval_results or goal_check result when present
+  - PR URL, merge commit, checks/CI status, or explicit blocker
+- A terminal failed child is still useful evidence. Decide whether to rescope,
+  retry with a better child goal, or mark blocked.
+
+Stop rules:
+- Do not stop just because one item is accepted. Stop only when the full session
+  goal is satisfied.
+- If the full goal is satisfied, update the rendered Session control path:
+  {
+    "state": "stopped",
+    "reason": "PM accepted evidence satisfies the session goal",
+    "stop_reason": "goal_met",
+    "schema_version": 1
+  }
+- If no useful work remains and the blocker is genuinely terminal, update the
+  Session control path with stop_reason `unresolvable_error` and record the
+  exact blocker in current_state.md.
+
+Guardrails:
+- Do not write child request files. The dispatcher owns child_requests/.
+- Do not implement child work directly.
+- Do not create more than one selected item at a time.
+- Keep PM state concise and operational.
+- Write supporting review notes under the iteration harness output root when
+  useful.
+
+Use Codex.

loopy_loop/templates/pm_planner_dispatcher/loopy_loop_config.yaml

@@ -0,0 +1,24 @@
+goal_file: loopy_loop_goal.txt
+workflow_set: pm_planner_dispatcher
+max_turns: 120
+goal_check_consecutive_failures_cap: 3
+team_harness_provider: "codex"
+team_harness_model: "gpt-5.5"
+team_harness_agents:
+  - "codex"
+  - "claude"
+  - "gemini"
+team_harness_agent_models:
+  codex: "gpt-5.5"
+team_harness_agent_reasoning_efforts:
+  codex: "high"
+# Optional coordinator retry controls. Omit to use team-harness defaults.
+# team_harness_max_retries: 8
+# team_harness_retry_base_delay_s: 2.0
+# team_harness_retry_max_delay_s: 60.0
+team_harness_api_base: "https://openrouter.ai/api/v1"
+team_harness_api_key_env: "OPENROUTER_API_KEY"
+team_harness_system_prompt_extension: |
+  This session is a PM orchestration loop. It should manage work and dispatch
+  concrete implementation goals to child sessions. It should not implement the
+  child work directly.

loopy_loop/templates/pm_planner_dispatcher/loopy_loop_goal.txt

@@ -0,0 +1 @@
+Manage project work by selecting one concrete implementation item at a time, dispatching it to a child implementation loop, and reviewing the child evidence before accepting completion.

loopy_loop/worker.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import sys
+import time
+import traceback
+
+import httpx
+
+from loopy_loop.config import ConfigError
+from loopy_loop.config import load_workflow_config
+from loopy_loop.config import workflow_set_workflows_dir_path
+from loopy_loop.harness_runner import run_harness_iteration
+from loopy_loop.harness_runner import write_iteration_artifacts
+from loopy_loop.models import FinishedRequest
+from loopy_loop.models import IterationResult
+from loopy_loop.models import RootConfigSnapshot
+from loopy_loop.models import TaskResponse
+from loopy_loop.sessions import child_requests_dir_path
+from loopy_loop.sessions import control_path
+from loopy_loop.sessions import ensure_iteration_dir
+from loopy_loop.sessions import eval_checks_dir_path
+from loopy_loop.sessions import finished_path
+from loopy_loop.sessions import GOAL_CHECK_FILENAME
+from loopy_loop.sessions import harness_outputs_dir_path
+from loopy_loop.sessions import iteration_harness_output_root
+from loopy_loop.sessions import pending_finished_request_path
+from loopy_loop.sessions import project_state_dir_path
+from loopy_loop.sessions import session_dir_path
+from loopy_loop.sessions import session_goal_path
+from loopy_loop.sessions import updates_from_user_path
+
+# Internal retry constants for /finished — not configurable externally.
+# If all retries fail, the exception propagates and the process exits;
+# the next invocation recovers via the completed-task or abandoned-task path in /register.
+_FINISHED_RETRY_ATTEMPTS = 2
+_FINISHED_RETRY_BACKOFF_SECONDS = 1.0
+
+
+class FatalAssignmentError(Exception):
+    def __init__(
+        self, *, finished_assignment: FinishedAssignment, message: str
+    ) -> None:
+        super().__init__(message)
+        self.finished_assignment = finished_assignment
+
+
+@dataclass(frozen=True)
+class FinishedAssignment:
+    request: FinishedRequest
+    pending_path: Path
+
+
+def run_worker_loop(*, repo_root: Path, coordinator_url: str) -> None:
+    base_url = coordinator_url.rstrip("/")
+    with httpx.Client(timeout=30.0) as client:
+        task = _post_register(client=client, coordinator_url=base_url)
+        while task.action == "run":
+            try:
+                finished_assignment = _run_task(repo_root=repo_root, task=task)
+            except FatalAssignmentError as exc:
+                print(str(exc), file=sys.stderr)
+                _post_finished(
+                    client=client,
+                    coordinator_url=base_url,
+                    request=exc.finished_assignment.request,
+                )
+                _clear_pending_finished_request(
+                    path=exc.finished_assignment.pending_path
+                )
+                sys.exit(2)
+            task = _post_finished(
+                client=client,
+                coordinator_url=base_url,
+                request=finished_assignment.request,
+            )
+            _clear_pending_finished_request(path=finished_assignment.pending_path)
+
+
+def _post_register(*, client: httpx.Client, coordinator_url: str) -> TaskResponse:
+    response = client.post(f"{coordinator_url}/register", json={})
+    response.raise_for_status()
+    return TaskResponse.model_validate(response.json())
+
+
+def _post_finished(
+    *, client: httpx.Client, coordinator_url: str, request: FinishedRequest
+) -> TaskResponse:
+    for attempt in range(1, _FINISHED_RETRY_ATTEMPTS + 1):
+        try:
+            response = client.post(
+                f"{coordinator_url}/finished", json=request.model_dump()
+            )
+            response.raise_for_status()
+            return TaskResponse.model_validate(response.json())
+        except httpx.HTTPError:
+            traceback.print_exc()
+            if attempt == _FINISHED_RETRY_ATTEMPTS:
+                raise
+            time.sleep(_FINISHED_RETRY_BACKOFF_SECONDS * attempt)
+    raise RuntimeError("unreachable")
+
+
+def _run_task(*, repo_root: Path, task: TaskResponse) -> FinishedAssignment:
+    if (
+        task.session_id is None
+        or task.workflow_set is None
+        or task.workflow_id is None
+        or task.iteration is None
+        or task.config_snapshot is None
+    ):
+        raise ConfigError("Incomplete run payload from coordinator")
+
+    config_snapshot = RootConfigSnapshot.model_validate(
+        task.config_snapshot.model_dump()
+    )
+    workflow_dir = (
+        workflow_set_workflows_dir_path(
+            repo_root=repo_root, workflow_set=task.workflow_set
+        )
+        / task.workflow_id
+    )
+    workflow_config = load_workflow_config(workflow_dir=workflow_dir)
+    prompt_text = (workflow_dir / "prompt.txt").read_text(encoding="utf-8")
+    iteration_dir = ensure_iteration_dir(
+        repo_root=repo_root,
+        session_id=task.session_id,
+        iteration=task.iteration,
+        workflow_id=task.workflow_id,
+    )
+    harness_output_root = iteration_harness_output_root(
+        repo_root=repo_root,
+        session_id=task.session_id,
+        iteration=task.iteration,
+        workflow_id=task.workflow_id,
+    )
+    rendered_prompt = _render_prompt(
+        config_snapshot=config_snapshot,
+        session_id=task.session_id,
+        workflow_set=task.workflow_set,
+        iteration=task.iteration,
+        workflow_id=task.workflow_id,
+        iteration_dir=iteration_dir,
+        harness_output_root=harness_output_root,
+        workflow_prompt=prompt_text,
+        emits_goal_check=workflow_config.emits_goal_check,
+        repo_root=repo_root,
+    )
+    fatal_error: str | None = None
+    try:
+        iteration_result = run_harness_iteration(
+            repo_root=repo_root,
+            config_snapshot=config_snapshot,
+            rendered_prompt=rendered_prompt,
+            harness_output_root=harness_output_root,
+        )
+    except ConfigError as exc:
+        fatal_error = str(exc)
+        iteration_result = IterationResult(
+            success=False, text=None, error=fatal_error, harness_run_id=""
+        )
+    except Exception as exc:
+        traceback.print_exc()
+        iteration_result = IterationResult(
+            success=False, text=None, error=str(exc), harness_run_id=""
+        )
+    write_iteration_artifacts(
+        iteration_dir=iteration_dir,
+        rendered_prompt=rendered_prompt,
+        iteration_result=iteration_result,
+    )
+    finished_request = FinishedRequest(
+        session_id=task.session_id,
+        workflow_id=task.workflow_id,
+        iteration=task.iteration,
+        success=iteration_result.success,
+        text=iteration_result.text,
+        error=iteration_result.error,
+    )
+    pending_path = _write_pending_finished_request(
+        repo_root=repo_root, request=finished_request
+    )
+    finished_assignment = FinishedAssignment(
+        request=finished_request, pending_path=pending_path
+    )
+    if fatal_error is not None:
+        raise FatalAssignmentError(
+            finished_assignment=finished_assignment, message=fatal_error
+        )
+    return finished_assignment
+
+
+def _write_pending_finished_request(
+    *, repo_root: Path, request: FinishedRequest
+) -> Path:
+    path = pending_finished_request_path(
+        repo_root=repo_root,
+        session_id=request.session_id,
+        iteration=request.iteration,
+        workflow_id=request.workflow_id,
+    )
+    path.write_text(json.dumps(request.model_dump(), indent=2), encoding="utf-8")
+    return path
+
+
+def _clear_pending_finished_request(*, path: Path) -> None:
+    path.unlink(missing_ok=True)
+
+
+def _render_prompt(
+    *,
+    config_snapshot: RootConfigSnapshot,
+    session_id: str,
+    workflow_set: str,
+    iteration: int,
+    workflow_id: str,
+    iteration_dir: Path,
+    harness_output_root: Path,
+    workflow_prompt: str,
+    emits_goal_check: bool = False,
+    repo_root: Path | None = None,
+) -> str:
+    root = repo_root or Path.cwd()
+    session_dir = session_dir_path(repo_root=root, session_id=session_id)
+    lines = [
+        "loopy-loop assignment",
+        "",
+        f"Goal: {config_snapshot.goal}",
+        "Completion criteria:",
+        *[f"- {item}" for item in config_snapshot.completion_criteria],
+        "Stop criteria:",
+        *[f"- {item}" for item in config_snapshot.stop_criteria],
+        "",
+        f"Session ID: {session_id}",
+        f"Workflow set: {workflow_set}",
+        f"Iteration: {iteration}",
+        f"Workflow ID: {workflow_id}",
+        f"Session directory: {session_dir}",
+        f"Session goal path: {session_goal_path(repo_root=root, session_id=session_id)}",
+        "Session project_state directory: "
+        f"{project_state_dir_path(repo_root=root, session_id=session_id)}",
+        "Session eval_checks directory: "
+        f"{eval_checks_dir_path(repo_root=root, session_id=session_id)}",
+        "Session updates_from_user path: "
+        f"{updates_from_user_path(repo_root=root, session_id=session_id)}",
+        "Session child_requests directory: "
+        f"{child_requests_dir_path(repo_root=root, session_id=session_id)}",
+        f"Session control path: {control_path(repo_root=root, session_id=session_id)}",
+        "Session finished ledger path: "
+        f"{finished_path(repo_root=root, session_id=session_id)}",
+        "Session harness outputs directory: "
+        f"{harness_outputs_dir_path(repo_root=root, session_id=session_id)}",
+        f"Iteration directory: {iteration_dir}",
+        f"Iteration harness output root: {harness_output_root}",
+    ]
+    if session_dir.parent.name == "children":
+        lines.append(f"Parent session directory: {session_dir.parent.parent}")
+    if workflow_id == "goal_check" or emits_goal_check:
+        lines.append(
+            f"goal_check.json output path: {iteration_dir / GOAL_CHECK_FILENAME}"
+        )
+    lines.extend(["", "Workflow body:", workflow_prompt])
+    return "\n".join(lines).rstrip() + "\n"