loopy-loop 0.2.0__py3-none-any.whl

loopy_loop/sessions.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import uuid
+
+from loopy_loop.config import LOOPY_DIRNAME
+from loopy_loop.models import utc_now
+
+SESSIONS_DIRNAME = "sessions"
+ITERATIONS_DIRNAME = "iterations"
+CHILDREN_DIRNAME = "children"
+CHILD_REQUESTS_DIRNAME = "child_requests"
+SESSION_METADATA_FILENAME = "session.json"
+STATE_FILENAME = "state.json"
+CHILDREN_FILENAME = "children.json"
+PARENT_FILENAME = "parent.json"
+GOAL_FILENAME = "goal.md"
+EVENTS_FILENAME = "events.jsonl"
+PROJECT_STATE_DIRNAME = "project_state"
+EVAL_CHECKS_DIRNAME = "eval_checks"
+HARNESS_OUTPUTS_DIRNAME = "harness_outputs"
+UPDATES_FROM_USER_FILENAME = "updates_from_user.md"
+FINISHED_FILENAME = "finished.md"
+PROMPT_FILENAME = "prompt.txt"
+RESULT_FILENAME = "result.json"
+RESULT_TEXT_FILENAME = "result_text.txt"
+HARNESS_RUN_ID_FILENAME = "harness_run_id.txt"
+PENDING_FINISHED_REQUEST_FILENAME = "pending_finished_request.json"
+CONTROL_FILENAME = "control.json"
+GOAL_CHECK_FILENAME = "goal_check.json"
+
+
+def create_session_id(*, goal_hash: str) -> str:
+    stamp = utc_now().strftime("%Y%m%d_%H%M%S")
+    unique = uuid.uuid4().hex[:8]
+    return f"{stamp}_{goal_hash}_{unique}"
+
+
+def create_session_dir(
+    *,
+    repo_root: Path,
+    session_id: str,
+    goal_hash: str,
+    goal: str = "",
+    workflow_set: str,
+    parent_session_id: str | None = None,
+) -> Path:
+    created_at = utc_now().isoformat().replace("+00:00", "Z")
+    if parent_session_id is None:
+        session_dir = sessions_root_path(repo_root=repo_root) / session_id
+    else:
+        session_dir = (
+            session_dir_path(repo_root=repo_root, session_id=parent_session_id)
+            / CHILDREN_DIRNAME
+            / session_id
+        )
+    session_dir.mkdir(parents=True, exist_ok=True)
+    metadata_path = session_dir / SESSION_METADATA_FILENAME
+    if not metadata_path.exists():
+        payload = {
+            "session_id": session_id,
+            "goal_hash": goal_hash,
+            "workflow_set": workflow_set,
+            "parent_session_id": parent_session_id,
+            "created_at": created_at,
+        }
+        metadata_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    if parent_session_id is not None:
+        parent_path = session_dir / PARENT_FILENAME
+        if not parent_path.exists():
+            payload = {
+                "schema_version": 1,
+                "parent_session_id": parent_session_id,
+                "parent_relative_path": "../..",
+                "created_at": created_at,
+            }
+            parent_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    goal_path = session_dir / GOAL_FILENAME
+    if goal and not goal_path.exists():
+        goal_path.write_text(goal.rstrip() + "\n", encoding="utf-8")
+    children = session_dir / CHILDREN_FILENAME
+    if not children.exists():
+        payload = {"schema_version": 1, "children": []}
+        children.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    child_requests_dir_path(repo_root=repo_root, session_id=session_id).mkdir(
+        parents=True, exist_ok=True
+    )
+    events_path = session_dir / EVENTS_FILENAME
+    if not events_path.exists():
+        events_path.write_text("", encoding="utf-8")
+    control_path(repo_root=repo_root, session_id=session_id)
+    updates_path = updates_from_user_path(repo_root=repo_root, session_id=session_id)
+    if not updates_path.exists():
+        updates_path.write_text("", encoding="utf-8")
+    project_state_dir_path(repo_root=repo_root, session_id=session_id).mkdir(
+        parents=True, exist_ok=True
+    )
+    finished = finished_path(repo_root=repo_root, session_id=session_id)
+    if not finished.exists():
+        finished.write_text("# Finished Work\n", encoding="utf-8")
+    eval_checks_dir_path(repo_root=repo_root, session_id=session_id).mkdir(
+        parents=True, exist_ok=True
+    )
+    harness_outputs_dir_path(repo_root=repo_root, session_id=session_id).mkdir(
+        parents=True, exist_ok=True
+    )
+    iterations_dir_path(repo_root=repo_root, session_id=session_id).mkdir(
+        parents=True, exist_ok=True
+    )
+    return session_dir
+
+
+def sessions_root_path(*, repo_root: Path) -> Path:
+    return repo_root / LOOPY_DIRNAME / SESSIONS_DIRNAME
+
+
+def session_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    root = sessions_root_path(repo_root=repo_root)
+    direct = root / session_id
+    if direct.exists():
+        return direct
+    if root.exists():
+        for candidate in sorted(root.rglob(session_id)):
+            if candidate.is_dir() and candidate.name == session_id:
+                return candidate
+    return direct
+
+
+def state_path(*, repo_root: Path, session_id: str) -> Path:
+    return session_dir_path(repo_root=repo_root, session_id=session_id) / STATE_FILENAME
+
+
+def children_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id) / CHILDREN_FILENAME
+    )
+
+
+def parent_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id) / PARENT_FILENAME
+    )
+
+
+def child_requests_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / CHILD_REQUESTS_DIRNAME
+    )
+
+
+def child_sessions_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id) / CHILDREN_DIRNAME
+    )
+
+
+def session_goal_path(*, repo_root: Path, session_id: str) -> Path:
+    return session_dir_path(repo_root=repo_root, session_id=session_id) / GOAL_FILENAME
+
+
+def latest_top_level_state_path(*, repo_root: Path) -> Path | None:
+    root = sessions_root_path(repo_root=repo_root)
+    if not root.exists():
+        return None
+    candidates = [
+        path / STATE_FILENAME
+        for path in root.iterdir()
+        if path.is_dir() and (path / STATE_FILENAME).exists()
+    ]
+    return sorted(candidates)[-1] if candidates else None
+
+
+def latest_state_path(*, repo_root: Path) -> Path | None:
+    root = sessions_root_path(repo_root=repo_root)
+    if not root.exists():
+        return None
+    candidates = sorted(root.rglob(STATE_FILENAME))
+    return candidates[-1] if candidates else None
+
+
+def iterations_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / ITERATIONS_DIRNAME
+    )
+
+
+def project_state_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / PROJECT_STATE_DIRNAME
+    )
+
+
+def eval_checks_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / EVAL_CHECKS_DIRNAME
+    )
+
+
+def harness_outputs_dir_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / HARNESS_OUTPUTS_DIRNAME
+    )
+
+
+def updates_from_user_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        session_dir_path(repo_root=repo_root, session_id=session_id)
+        / UPDATES_FROM_USER_FILENAME
+    )
+
+
+def finished_path(*, repo_root: Path, session_id: str) -> Path:
+    return (
+        project_state_dir_path(repo_root=repo_root, session_id=session_id)
+        / FINISHED_FILENAME
+    )
+
+
+def iteration_dir_name(*, iteration: int, workflow_id: str) -> str:
+    return f"{iteration:04d}_{workflow_id}"
+
+
+def iteration_dir_path(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str
+) -> Path:
+    return iterations_dir_path(repo_root=repo_root, session_id=session_id) / (
+        iteration_dir_name(iteration=iteration, workflow_id=workflow_id)
+    )
+
+
+def iteration_harness_output_root(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str
+) -> Path:
+    return harness_outputs_dir_path(
+        repo_root=repo_root, session_id=session_id
+    ) / iteration_dir_name(iteration=iteration, workflow_id=workflow_id)
+
+
+def ensure_iteration_dir(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str
+) -> Path:
+    iteration_dir = iteration_dir_path(
+        repo_root=repo_root,
+        session_id=session_id,
+        iteration=iteration,
+        workflow_id=workflow_id,
+    )
+    iteration_dir.mkdir(parents=True, exist_ok=True)
+    return iteration_dir
+
+
+def pending_finished_request_path(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str
+) -> Path:
+    return (
+        iteration_dir_path(
+            repo_root=repo_root,
+            session_id=session_id,
+            iteration=iteration,
+            workflow_id=workflow_id,
+        )
+        / PENDING_FINISHED_REQUEST_FILENAME
+    )
+
+
+def result_path(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str
+) -> Path:
+    return (
+        iteration_dir_path(
+            repo_root=repo_root,
+            session_id=session_id,
+            iteration=iteration,
+            workflow_id=workflow_id,
+        )
+        / RESULT_FILENAME
+    )
+
+
+def control_path(*, repo_root: Path, session_id: str) -> Path:
+    path = (
+        session_dir_path(repo_root=repo_root, session_id=session_id) / CONTROL_FILENAME
+    )
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "state": "running",
+            "reason": "session active",
+            "stop_reason": None,
+            "schema_version": 1,
+        }
+        path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return path
+
+
+def goal_check_path(
+    *, repo_root: Path, session_id: str, iteration: int, workflow_id: str = "goal_check"
+) -> Path:
+    return (
+        ensure_iteration_dir(
+            repo_root=repo_root,
+            session_id=session_id,
+            iteration=iteration,
+            workflow_id=workflow_id,
+        )
+        / GOAL_CHECK_FILENAME
+    )

loopy_loop/state_store.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+import os
+from pathlib import Path
+from typing import TypeVar
+
+from filelock import FileLock
+
+from loopy_loop.config import LOOPY_DIRNAME
+from loopy_loop.models import DEFAULT_LOCK_TIMEOUT_SECONDS
+from loopy_loop.models import LoopState
+from loopy_loop.models import utc_now
+from loopy_loop.sessions import latest_top_level_state_path
+from loopy_loop.sessions import state_path as session_state_path
+
+STATE_FILENAME = "state.json"
+LOCK_FILENAME = "state.json.lock"
+TEMP_FILENAME = "state.json.tmp"
+ARCHIVE_PREFIX = "state.json.archive_"
+TERMINAL_STATUSES = {"stopped", "goal_met", "failed", "max_turns"}
+
+T = TypeVar("T")
+
+
+class StateStore:
+    def __init__(
+        self,
+        *,
+        repo_root: Path,
+        state_path: Path | None = None,
+        lock_timeout_seconds: float = DEFAULT_LOCK_TIMEOUT_SECONDS,
+    ) -> None:
+        self.repo_root = repo_root
+        self.loopy_dir = repo_root / LOOPY_DIRNAME
+        self.state_path = state_path
+        self.lock_timeout_seconds = lock_timeout_seconds
+
+    def read_state(self) -> LoopState | None:
+        with self._lock():
+            return self._read_state_unlocked()
+
+    def write_state(self, *, state: LoopState) -> LoopState:
+        with self._lock():
+            self._write_state_unlocked(state=state)
+            return state
+
+    def mutate(self, mutator: Callable[[LoopState | None], tuple[LoopState, T]]) -> T:
+        with self._lock():
+            current = self._read_state_unlocked()
+            next_state, result = mutator(current)
+            self._write_state_unlocked(state=next_state)
+            return result
+
+    def archive_state(self) -> Path | None:
+        with self._lock():
+            current = self._read_state_unlocked()
+            if current is None or self.state_path is None:
+                return None
+            archive_path = self._archive_path()
+            os.replace(self.state_path, archive_path)
+            return archive_path
+
+    def clear_state(self) -> None:
+        with self._lock():
+            if self.state_path is not None and self.state_path.exists():
+                self.state_path.unlink()
+
+    def is_terminal_state(self, *, state: LoopState) -> bool:
+        return state.status in TERMINAL_STATUSES
+
+    def _lock(self) -> FileLock:
+        self.loopy_dir.mkdir(parents=True, exist_ok=True)
+        lock_path = self._effective_state_path()
+        if lock_path is None:
+            lock_path = self.loopy_dir / LOCK_FILENAME
+        else:
+            lock_path = lock_path.with_name(LOCK_FILENAME)
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        return FileLock(str(lock_path), timeout=self.lock_timeout_seconds)
+
+    def _read_state_unlocked(self) -> LoopState | None:
+        state_path = self._effective_state_path()
+        if state_path is None or not state_path.exists():
+            return None
+        self.state_path = state_path
+        raw = state_path.read_text(encoding="utf-8")
+        return LoopState.model_validate_json(raw)
+
+    def _write_state_unlocked(self, *, state: LoopState) -> None:
+        if self.state_path is None:
+            self.state_path = session_state_path(
+                repo_root=self.repo_root, session_id=state.active_session_id
+            )
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = self.state_path.with_name(TEMP_FILENAME)
+        payload = state.model_dump_json(indent=2)
+        temp_path.write_text(payload, encoding="utf-8")
+        os.replace(temp_path, self.state_path)
+
+    def _archive_path(self) -> Path:
+        if self.state_path is None:
+            raise RuntimeError("Cannot archive without a state path")
+        stamp = utc_now().strftime("%Y%m%dT%H%M%SZ")
+        return self.state_path.with_name(f"{ARCHIVE_PREFIX}{stamp}.json")
+
+    def _effective_state_path(self) -> Path | None:
+        if self.state_path is not None:
+            return self.state_path
+        return latest_top_level_state_path(repo_root=self.repo_root)

loopy_loop/templates/inner_outer_eval/.gitignore

@@ -0,0 +1,4 @@
+.loopy_loop/sessions/
+.loopy_loop/state.json
+.loopy_loop/state.json.lock
+.loopy_loop/state.json.archive_*.json

loopy_loop/templates/inner_outer_eval/.loopy_loop/workflow_sets/inner_outer_eval/workflows/eval_reviewer/config.yaml

@@ -0,0 +1,11 @@
+enabled: true
+priority: 100
+run_every: 1
+must_follow: null
+not_before_iteration: 0
+run_on_start: true
+run_after_successes:
+  workflow_id: inner
+  every: 10
+description: |
+  Create or refresh high-level eval-banana checks for the active session.

loopy_loop/templates/inner_outer_eval/.loopy_loop/workflow_sets/inner_outer_eval/workflows/eval_reviewer/prompt.txt

@@ -0,0 +1,97 @@
+You are the eval reviewer for this loopy-loop session.
+
+Your job is to create and maintain high-level eval-banana scenarios that can
+decide whether the configured goal and completion criteria have been met.
+Keep the scenarios general enough to allow different implementation choices.
+
+Inputs available in the rendered assignment:
+- Goal, completion criteria, and stop criteria
+- Session directory
+- Session project_state directory
+- Session eval_checks directory
+- Session finished ledger path
+- Session harness outputs directory
+- Iteration directory
+- Iteration harness output root
+
+Goal source of truth:
+- Treat the rendered Goal input and loopy_loop_goal.txt as canonical.
+- Do not infer or restate the goal from project_state files.
+- Use project_state only to understand progress, decisions, memory, and eval
+  history.
+
+State contract:
+- Create the session project_state directory if it does not exist.
+- Create the session eval_checks directory if it does not exist.
+- Ensure project_state/README.md explains:
+  - loopy_loop_goal.txt is the goal source of truth
+  - memory.md is essential durable facts only
+  - current_state.md is live status and latest eval headline only
+  - eval_results.md owns eval check inventory, run history, and report links
+  - finished.md is outer-owned accepted completions only
+- Ensure project_state/memory.md exists and stays limited to essential durable
+  facts future iterations must keep in working memory. It is not iteration
+  history and not decision rationale.
+- Read and update project_state/current_state.md and project_state/eval_results.md.
+- Read project_state/memory.md when creating or refreshing checks.
+- Do not mark implementation tasks complete. That belongs to outer after review.
+
+Eval state split:
+- Keep eval check inventory, commands, validation result, run result, report
+  paths, and missing/weak checks in project_state/eval_results.md.
+- Keep project_state/current_state.md limited to eval readiness headline and
+  next action.
+- Do not copy full eval reports into current_state.md.
+
+PR and merge guardrail:
+- Do not create branches, open PRs, or merge PRs. Eval workflows only create or
+  refresh eval checks and eval state.
+
+Eval-banana contract:
+- Check files are YAML files.
+- Use schema_version: 1.
+- Use unique check ids.
+- Only create harness_judge checks. Use them to describe the desired outcomes.
+  These can be kept high level.
+- Do not create deterministic checks. Deterministic checks are forbidden for
+  this workflow, even for objective file, structure, command, or data
+  assertions.
+- target_paths are resolved from the repo root.
+- Session-local checks should evaluate the repo by running eval-banana from the
+  repo root with --cwd . and --check-dir <session eval_checks directory>.
+- The eval runner will run only this session's checks with:
+  eval-banana run --cwd . --check-dir <session eval_checks directory> --output-dir <session directory>/eval_results
+
+What to do:
+1. Read .agents/skills/eval-banana/SKILL.md if present. If it is absent, use
+   the eval-banana contract above.
+2. Read the session project_state files if they exist, including memory.md.
+3. Inspect the repo enough to understand the current implementation shape.
+4. Create or refresh YAML harness_judge checks under the session eval_checks
+   directory.
+5. Make the harness_judge checks high-level and outcome-focused. Avoid brittle
+   assertions about implementation details unless the completion criteria
+   require them.
+6. Run eval-banana validate with --check-dir for the session eval_checks
+   directory when eval-banana is available.
+7. Update project_state/eval_results.md with:
+   - active checks
+   - which goal condition each check covers
+   - last validation result
+   - last run result, if one exists
+   - known weak or missing checks
+8. Update project_state/current_state.md with the current eval readiness state.
+9. Update project_state/memory.md only if eval work discovers an essential
+   durable fact future iterations must remember.
+10. Write any supporting reports under the iteration harness output root when useful.
+
+Good check coverage should answer:
+- Does the repo contain a runnable implementation for the goal?
+- Are the configured completion criteria observably satisfied?
+- Are there clear local run/test instructions where relevant?
+- Are important user-facing workflows covered at a high level?
+
+If eval-banana is unavailable, still write the YAML checks and record that
+validation could not be run.
+
+Use Codex.

loopy_loop/templates/inner_outer_eval/.loopy_loop/workflow_sets/inner_outer_eval/workflows/eval_runner/config.yaml

@@ -0,0 +1,12 @@
+enabled: true
+priority: 90
+run_every: 1
+must_follow: eval_reviewer
+not_before_iteration: 10
+run_after_successes:
+  workflow_id: inner
+  every: 10
+emits_goal_check: true
+description: |
+  Run the session eval-banana checks and write goal_check.json. The loop stops
+  only when all checks pass.

loopy_loop/templates/inner_outer_eval/.loopy_loop/workflow_sets/inner_outer_eval/workflows/eval_runner/prompt.txt

@@ -0,0 +1,86 @@
+You are the eval runner for this loopy-loop session.
+
+Your job is to run the session eval-banana checks and write the goal_check.json
+file requested in the rendered assignment.
+
+Inputs available in the rendered assignment:
+- Goal, completion criteria, and stop criteria
+- Session directory
+- Session project_state directory
+- Session eval_checks directory
+- Session finished ledger path
+- Session harness outputs directory
+- Iteration directory
+- Iteration harness output root
+- Session control path
+- goal_check.json output path
+
+Goal source of truth:
+- Treat the rendered Goal input and loopy_loop_goal.txt as canonical.
+- Do not infer or restate the goal from project_state files.
+- Use project_state only to understand progress, memory, and eval history.
+
+Eval state split:
+- project_state/eval_results.md owns eval commands, validation status, run ids,
+  report paths, score, pass/fail history, and failed-check details.
+- project_state/current_state.md should contain only the latest eval headline
+  and the next action.
+- Do not copy full eval reports into current_state.md.
+
+PR and merge guardrail:
+- Do not create branches, open PRs, or merge PRs. Eval workflows only run evals,
+  update eval state, and write goal_check.json.
+
+What to do:
+1. Read project_state/memory.md, project_state/current_state.md, and
+   project_state/eval_results.md if they exist.
+2. Confirm the session eval_checks directory exists and contains YAML checks.
+3. If eval-banana is available, create <session directory>/eval_results and run
+   from the repo root. Pass --cwd . so session-local checks evaluate repo-root
+   paths:
+   eval-banana validate --cwd . --check-dir <session eval_checks directory>
+   eval-banana run --cwd . --check-dir <session eval_checks directory> --output-dir <session directory>/eval_results
+4. Read the eval-banana console output and the latest report.json/report.md
+   under <session directory>/eval_results/<run_id>/ when available.
+5. Update project_state/eval_results.md as a curated eval index with:
+   - iteration number
+   - commands run
+   - validation status
+   - run id and report path when available
+   - score and pass/fail status
+   - failed checks with concise reasons
+   - next eval-facing action
+6. Update project_state/current_state.md with a short latest-eval summary:
+   goal_met, pass/fail, run id/report path, and what should happen next.
+7. Update project_state/memory.md only if the eval result changes an essential
+   durable fact future iterations must remember.
+8. Do not update project_state/finished.md. Do not mark implementation work
+   complete.
+9. Write supporting eval logs or reports under the iteration harness output root
+   when useful.
+10. Write goal_check.json to the exact path from the rendered assignment.
+11. If and only if goal_check.json has goal_met true, update the rendered
+    Session control path to stop the loop with stop_reason goal_met.
+
+goal_check.json schema:
+{
+  "goal_met": false,
+  "reason": "brief explanation",
+  "schema_version": 1
+}
+
+Set goal_met to true only when:
+- eval-banana validation succeeds,
+- eval-banana run succeeds,
+- all scenarios pass.
+
+If eval-banana is unavailable, checks are missing, validation fails, or any
+scenario fails, set goal_met to false and explain why in the reason.
+
+Session control stop schema:
+{
+  "state": "stopped",
+  "reason": "eval-banana validation and run passed; all scenarios passed",
+  "stop_reason": "goal_met",
+  "schema_version": 1
+}

loopy_loop/templates/inner_outer_eval/.loopy_loop/workflow_sets/inner_outer_eval/workflows/inner/config.yaml

@@ -0,0 +1,8 @@
+enabled: true
+priority: 20
+run_every: 1
+must_follow: outer
+not_before_iteration: 1
+description: |
+  Implement the first available leaf task from the session plan, run relevant
+  checks, and mark the leaf task as waiting for outer-loop review.