autoloop 0.1.0__tar.gz

autoloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelo Rauter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autoloop-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: autoloop
+Version: 0.1.0
+Summary: Protocol-driven agent loops for shipping real code with less babysitting.
+Author: Marcelo Rauter
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mrauter1/autoloop
+Project-URL: Repository, https://github.com/mrauter1/autoloop
+Project-URL: Issues, https://github.com/mrauter1/autoloop/issues
+Keywords: llm,agent,orchestration,cli,codex
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# Autoloop
+
+Protocol-driven agent loops for shipping real code with less babysitting.
+
+Autoloop is a stateful orchestration runtime for repository work. It runs plan, implement, and test producer/verifier pairs with durable state, resumable runs, phase scoping, provider-neutral sessions, and git-backed checkpoints.
+
+## Requirements
+
+- Python 3.10+
+- One supported provider CLI:
+  - `codex` for `provider.name: codex` (default)
+  - `claude` for `provider.name: claude`, with local `claude auth status` already working
+- `git` is optional when running with `--no-git`
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install autoloop
+autoloop --help
+```
+
+Install from this repository:
+
+```bash
+python -m pip install -e .
+autoloop --help
+python -m autoloop --help
+```
+
+Or use the bundled installer:
+
+```bash
+./install_autoloop.sh
+```
+
+The installer sets up Autoloop itself and the packaged skill, but it does not install provider CLIs for you. Install `codex` or `claude` separately based on the provider you plan to run.
+
+## Configuration
+
+Autoloop reads configuration from these directories, in this order:
+
+1. `$XDG_CONFIG_HOME/autoloop/` or `~/.config/autoloop/`
+2. the selected workspace root passed to `--workspace`
+
+Within each directory it looks for:
+
+- `autoloop.yaml`
+- `autoloop.config`
+- legacy read-only fallback: `superloop.yaml`
+- legacy read-only fallback: `superloop.config`
+
+If more than one config file exists in the same directory, Autoloop fails fast instead of guessing.
+
+Use the nested provider shape for new configs:
+
+```yaml
+provider:
+  name: codex
+  codex:
+    model: gpt-5.4
+    model_effort: null
+  claude:
+    model: null
+    effort: null
+    permission_strategy: inherit
+runtime:
+  pairs: plan,implement,test
+  max_iterations: 15
+  phase_mode: single
+  intent_mode: preserve
+  full_auto_answers: false
+  no_git: false
+```
+
+Notes:
+
+- Legacy flat Codex keys `provider.model` and `provider.model_effort` are still read for backward compatibility.
+- `--model` and `--model-effort` are Codex-only CLI overrides.
+- Claude defaults intentionally inherit the operator's existing Claude Code environment. Default Claude runs do not add strict mode, `--bare`, tool restriction flags, or `stream-json`.
+- `runtime.full_auto_answers` now uses the active provider instead of being Codex-only.
+
+## Runtime State
+
+Fresh runs write state under `.autoloop/`.
+
+For the first Autoloop release, resume and task listing can still read legacy `.superloop/` workspaces when no `.autoloop/` state exists for the requested task or run.
+
+Session files now store provider-neutral `provider` and `session_id` fields. Legacy Codex session files that only contain `thread_id` remain load-compatible.
+
+## Claude Validation
+
+Maintainer live-validation steps for inherited-environment Claude repos and resume config-drift checks are recorded in [docs/claude_rollout_checklist.md](docs/claude_rollout_checklist.md).
+
+## Skill
+
+The packaged Autoloop skill lives at `src/autoloop/skill/SKILL.md`.

autoloop-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Autoloop
+
+Protocol-driven agent loops for shipping real code with less babysitting.
+
+Autoloop is a stateful orchestration runtime for repository work. It runs plan, implement, and test producer/verifier pairs with durable state, resumable runs, phase scoping, provider-neutral sessions, and git-backed checkpoints.
+
+## Requirements
+
+- Python 3.10+
+- One supported provider CLI:
+  - `codex` for `provider.name: codex` (default)
+  - `claude` for `provider.name: claude`, with local `claude auth status` already working
+- `git` is optional when running with `--no-git`
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install autoloop
+autoloop --help
+```
+
+Install from this repository:
+
+```bash
+python -m pip install -e .
+autoloop --help
+python -m autoloop --help
+```
+
+Or use the bundled installer:
+
+```bash
+./install_autoloop.sh
+```
+
+The installer sets up Autoloop itself and the packaged skill, but it does not install provider CLIs for you. Install `codex` or `claude` separately based on the provider you plan to run.
+
+## Configuration
+
+Autoloop reads configuration from these directories, in this order:
+
+1. `$XDG_CONFIG_HOME/autoloop/` or `~/.config/autoloop/`
+2. the selected workspace root passed to `--workspace`
+
+Within each directory it looks for:
+
+- `autoloop.yaml`
+- `autoloop.config`
+- legacy read-only fallback: `superloop.yaml`
+- legacy read-only fallback: `superloop.config`
+
+If more than one config file exists in the same directory, Autoloop fails fast instead of guessing.
+
+Use the nested provider shape for new configs:
+
+```yaml
+provider:
+  name: codex
+  codex:
+    model: gpt-5.4
+    model_effort: null
+  claude:
+    model: null
+    effort: null
+    permission_strategy: inherit
+runtime:
+  pairs: plan,implement,test
+  max_iterations: 15
+  phase_mode: single
+  intent_mode: preserve
+  full_auto_answers: false
+  no_git: false
+```
+
+Notes:
+
+- Legacy flat Codex keys `provider.model` and `provider.model_effort` are still read for backward compatibility.
+- `--model` and `--model-effort` are Codex-only CLI overrides.
+- Claude defaults intentionally inherit the operator's existing Claude Code environment. Default Claude runs do not add strict mode, `--bare`, tool restriction flags, or `stream-json`.
+- `runtime.full_auto_answers` now uses the active provider instead of being Codex-only.
+
+## Runtime State
+
+Fresh runs write state under `.autoloop/`.
+
+For the first Autoloop release, resume and task listing can still read legacy `.superloop/` workspaces when no `.autoloop/` state exists for the requested task or run.
+
+Session files now store provider-neutral `provider` and `session_id` fields. Legacy Codex session files that only contain `thread_id` remain load-compatible.
+
+## Claude Validation
+
+Maintainer live-validation steps for inherited-environment Claude repos and resume config-drift checks are recorded in [docs/claude_rollout_checklist.md](docs/claude_rollout_checklist.md).
+
+## Skill
+
+The packaged Autoloop skill lives at `src/autoloop/skill/SKILL.md`.

autoloop-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autoloop"
+version = "0.1.0"
+description = "Protocol-driven agent loops for shipping real code with less babysitting."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Marcelo Rauter" }
+]
+dependencies = [
+  "PyYAML>=6.0",
+]
+keywords = ["llm", "agent", "orchestration", "cli", "codex"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/mrauter1/autoloop"
+Repository = "https://github.com/mrauter1/autoloop"
+Issues = "https://github.com/mrauter1/autoloop/issues"
+
+[project.scripts]
+autoloop = "autoloop.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["autoloop*"]
+
+[tool.setuptools.package-data]
+autoloop = [
+  "templates/*.md",
+  "skill/SKILL.md",
+]

autoloop-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

autoloop-0.1.0/src/autoloop/__init__.py

@@ -0,0 +1 @@
+"""Autoloop package."""

autoloop-0.1.0/src/autoloop/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+raise SystemExit(main())

autoloop-0.1.0/src/autoloop/loop_control.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+CONTROL_SCHEMA_ID = "docloop.loop_control/v1"
+
+PROMISE_COMPLETE = "COMPLETE"
+PROMISE_INCOMPLETE = "INCOMPLETE"
+PROMISE_BLOCKED = "BLOCKED"
+PROMISE_VALUES = {PROMISE_COMPLETE, PROMISE_INCOMPLETE, PROMISE_BLOCKED}
+
+CANONICAL_BLOCK_RE = re.compile(
+    r"<loop-control>\s*(.*?)\s*</loop-control>",
+    re.DOTALL | re.IGNORECASE,
+)
+LEGACY_QUESTION_RE = re.compile(r"<question>(.*?)</question>", re.DOTALL | re.IGNORECASE)
+PROMISE_LINE_RE = re.compile(
+    r"^\s*<promise>(COMPLETE|INCOMPLETE|BLOCKED)</promise>\s*$",
+    re.IGNORECASE,
+)
+UNCHECKED_BOX_RE = re.compile(r"^\s*-\s\[ \]", re.MULTILINE)
+
+
+class LoopControlParseError(ValueError):
+    """Raised when loop-control output is malformed or conflicting."""
+
+
+@dataclass(frozen=True)
+class LoopQuestion:
+    text: str
+    best_supposition: str | None = None
+
+
+@dataclass(frozen=True)
+class LoopControl:
+    question: LoopQuestion | None
+    promise: str | None
+    source: Literal["canonical", "legacy", "none"]
+    raw_payload: str | None
+
+
+def last_non_empty_line(text: str) -> str:
+    for line in reversed(text.splitlines()):
+        if line.strip():
+            return line.strip()
+    return ""
+
+
+def parse_loop_control(stdout: str) -> LoopControl:
+    canonical_matches = list(CANONICAL_BLOCK_RE.finditer(stdout))
+    if len(canonical_matches) > 1:
+        raise LoopControlParseError("Multiple <loop-control> blocks found.")
+
+    if canonical_matches:
+        return _parse_canonical_control(stdout, canonical_matches[0])
+
+    return _parse_legacy_control(stdout)
+
+
+def criteria_all_checked(criteria_file: Path) -> bool:
+    criteria_text = criteria_file.read_text(encoding="utf-8")
+    return UNCHECKED_BOX_RE.search(criteria_text) is None
+
+
+def _parse_canonical_control(stdout: str, canonical_match: re.Match[str]) -> LoopControl:
+    prefix = stdout[: canonical_match.start()]
+    suffix = stdout[canonical_match.end() :]
+
+    if suffix.strip():
+        raise LoopControlParseError(
+            "Canonical <loop-control> output must be the last non-empty block in stdout."
+        )
+
+    if LEGACY_QUESTION_RE.search(prefix):
+        raise LoopControlParseError(
+            "Canonical <loop-control> output cannot be combined with legacy <question> tags."
+        )
+    legacy_promise_match = PROMISE_LINE_RE.fullmatch(last_non_empty_line(prefix))
+    if legacy_promise_match:
+        raise LoopControlParseError(
+            "Canonical <loop-control> output cannot be combined with legacy final-line <promise> tags."
+        )
+
+    raw_payload = canonical_match.group(1).strip()
+    try:
+        payload = json.loads(raw_payload)
+    except json.JSONDecodeError as exc:
+        raise LoopControlParseError(f"Invalid canonical loop-control JSON: {exc.msg}.") from exc
+
+    if not isinstance(payload, dict):
+        raise LoopControlParseError("Canonical loop-control payload must decode to a JSON object.")
+    _validate_canonical_schema(payload)
+
+    kind = payload.get("kind")
+    if kind == "question":
+        return _parse_canonical_question(payload, raw_payload)
+    if kind == "promise":
+        return _parse_canonical_promise(payload, raw_payload)
+    raise LoopControlParseError("Canonical loop-control kind must be 'question' or 'promise'.")
+
+
+def _parse_canonical_question(payload: dict[str, object], raw_payload: str) -> LoopControl:
+    if "promise" in payload:
+        raise LoopControlParseError("Canonical question payload must not include a promise field.")
+
+    question = _require_non_empty_string(payload.get("question"), "Canonical question payload requires 'question'.")
+    best_supposition = payload.get("best_supposition")
+    if best_supposition is not None:
+        best_supposition = _require_non_empty_string(
+            best_supposition,
+            "Canonical question payload best_supposition must be a non-empty string when provided.",
+        )
+
+    return LoopControl(
+        question=LoopQuestion(text=question, best_supposition=best_supposition),
+        promise=None,
+        source="canonical",
+        raw_payload=raw_payload,
+    )
+
+
+def _parse_canonical_promise(payload: dict[str, object], raw_payload: str) -> LoopControl:
+    if "question" in payload or "best_supposition" in payload:
+        raise LoopControlParseError(
+            "Canonical promise payload must not include question or best_supposition fields."
+        )
+
+    promise = _require_non_empty_string(payload.get("promise"), "Canonical promise payload requires 'promise'.")
+    promise = promise.upper()
+    if promise not in PROMISE_VALUES:
+        raise LoopControlParseError(
+            f"Canonical promise must be one of {PROMISE_COMPLETE}, {PROMISE_INCOMPLETE}, or {PROMISE_BLOCKED}, not {promise!r}."
+        )
+
+    return LoopControl(
+        question=None,
+        promise=promise,
+        source="canonical",
+        raw_payload=raw_payload,
+    )
+
+
+def _validate_canonical_schema(payload: dict[str, object]) -> None:
+    if payload.get("schema") != CONTROL_SCHEMA_ID:
+        raise LoopControlParseError(
+            f"Canonical loop-control schema must be {CONTROL_SCHEMA_ID!r}."
+        )
+
+
+def _parse_legacy_control(stdout: str) -> LoopControl:
+    question_match = LEGACY_QUESTION_RE.search(stdout)
+    promise_match = PROMISE_LINE_RE.fullmatch(last_non_empty_line(stdout))
+
+    question = None
+    if question_match:
+        question_text = question_match.group(1).strip()
+        question = LoopQuestion(text=question_text)
+
+    promise = promise_match.group(1).upper() if promise_match else None
+    if question or promise:
+        return LoopControl(question=question, promise=promise, source="legacy", raw_payload=None)
+
+    return LoopControl(question=None, promise=None, source="none", raw_payload=None)
+
+
+def _require_non_empty_string(value: object, message: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise LoopControlParseError(message)
+    return value.strip()