sisyphusfy 0.1.0__tar.gz

sisyphusfy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sisyphusfy contributors
+
+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.

sisyphusfy-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: sisyphusfy
+Version: 0.1.0
+Summary: Project-agnostic supervisor for disposable AI-agent sessions
+Requires-Python: >=3.10
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Dynamic: license-file

sisyphusfy-0.1.0/README.md

@@ -0,0 +1,331 @@
+# Sisyphusfy
+
+Fresh agent sessions. Persistent project progress.
+
+Sisyphusfy is a project-agnostic runner for executing software tasks through disposable AI-agent sessions. It keeps durable state in project files, supports multiple agent CLIs and model fallback, and avoids carrying an expensive conversation history from one task or specification to the next.
+
+## Why
+
+AI coding sessions become expensive and fragile when conversation history grows across unrelated specifications. Sisyphusfy treats the workspace as the source of truth:
+
+- one session performs a small unit of work;
+- task state and a concise handoff are written to disk;
+- failures, quota exhaustion, and timeouts can switch to another model;
+- the next session reconstructs only the necessary context;
+- a new specification starts with a fresh conversation.
+
+## Design principles
+
+1. The runner is not tied to a language, framework, repository layout, or OpenSpec.
+2. Agent CLIs are adapters, not dependencies of the loop engine.
+3. Task state is machine-checkable; handoff text is compact recovery context.
+4. Verification is performed by the runner, not merely claimed by the agent.
+5. Permission prompts and ambiguous choices stop safely instead of hanging forever.
+6. Commit, archive, and push are opt-in operations.
+7. Fresh context is the default; conversation continuation is explicit.
+
+## Installation
+
+**Repository**: https://github.com/lileililiwen/sisyphusfy
+**Website**: https://sisyphusfy.dev/
+**Releases**: https://github.com/lileililiwen/sisyphusfy/releases
+
+### pip / pipx
+
+```bash
+pip install sisyphusfy
+# or
+pipx install sisyphusfy
+```
+
+### npm
+
+```bash
+npm install -g sisyphusfy
+```
+
+### POSIX installer
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lileililiwen/sisyphusfy/main/install.sh | sh
+```
+
+### PowerShell installer (Windows)
+
+```powershell
+irm https://raw.githubusercontent.com/lileililiwen/sisyphusfy/main/install.ps1 | iex
+```
+
+### From a checkout
+
+```bash
+pip install -e .
+sisyphusfy --help
+```
+
+The package requires Python 3.10 or newer. OpenCode, CodeBuddy, and any
+project-specific verification tools are installed separately.
+
+## Quick start: one invocation
+
+Run a command with timeout:
+
+```bash
+sisyphusfy -t 30 -- echo "hello world"
+```
+
+Dry-run (shows command without executing):
+
+```bash
+sisyphusfy --dry-run -- echo "hello world"
+```
+
+JSON output for automation:
+
+```bash
+sisyphusfy --json -- python3 script.py
+```
+
+Deliver a prompt via stdin:
+
+```bash
+sisyphusfy -p "explain this repository" -- opencode run
+```
+
+Set working directory and environment variables:
+
+```bash
+sisyphusfy -d /path/to/project -t 60 -e API_KEY=abc123 -e DEBUG=1 -- my-agent
+```
+
+## Quick start: human-friendly workflow
+
+The high-level commands provide a simpler interface for common workflows.
+They automatically discover tasks, configuration, and agent settings.
+
+Initialize a project:
+
+```bash
+sisyphusfy init
+```
+
+Run an OpenSpec change:
+
+```bash
+sisyphusfy run my-change
+```
+
+Resume from durable state:
+
+```bash
+sisyphusfy resume
+```
+
+Check project status:
+
+```bash
+sisyphusfy status
+```
+
+Diagnose configuration issues:
+
+```bash
+sisyphusfy doctor
+```
+
+Dry-run to preview planned actions:
+
+```bash
+sisyphusfy run my-change --dry-run
+```
+
+Use JSON output for automation:
+
+```bash
+sisyphusfy status --json
+```
+
+Configuration precedence: CLI flags > `.sisyphusfy.toml` > user defaults > built-in defaults.
+
+The selected project directory (`--project-dir`, default `.`) is the working
+directory for every subprocess: agent, verification, workflow validation, and
+completion hooks. Relative paths resolve against it.
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [docs/configuration.md](docs/configuration.md) | Every `.sisyphusfy.toml` field: type, default, precedence, safety |
+| [docs/adapters.md](docs/adapters.md) | `AgentAdapter` protocol, registry, command construction, model fallback, failure classification, workflow adapters |
+| [docs/examples.md](docs/examples.md) | Minimal end-to-end setups for Python, Rust, JavaScript, Flutter, and .NET |
+| [docs/ci.md](docs/ci.md) | Continuous-integration usage and JSON result consumption |
+| [docs/security.md](docs/security.md) | Command-execution model and review checklist |
+| [docs/deployment.md](docs/deployment.md) | GitHub Pages and custom domain setup |
+
+## Quick start: durable loop
+
+The loop starts a fresh agent process for every iteration. The task file and
+handoff file are the durable state; previous agent conversation history is not
+restored.
+
+For a Markdown checklist:
+
+```bash
+sisyphusfy loop \
+  --task-path TASKS.md \
+  --handoff-path HANDOFF.md \
+  --completion-strategy markdown \
+  --adapter opencode \
+  --model-chain mimo-v2.5 minimax-3 \
+  --agent-timeout 2700 \
+  --max-iterations 20 \
+  --verification-command pytest
+```
+
+Use CodeBuddy instead:
+
+```bash
+sisyphusfy loop \
+  --task-path TASKS.md \
+  --handoff-path HANDOFF.md \
+  --completion-strategy markdown \
+  --adapter codebuddy \
+  --model-chain minimax-3
+```
+
+For an OpenSpec change, point the workflow adapter at the change directory:
+
+```bash
+sisyphusfy loop \
+  --task-path openspec/changes/my-change/tasks.md \
+  --handoff-path HANDOFF.md \
+  --workflow-type openspec \
+  --workflow-change-dir openspec/changes/my-change \
+  --workflow-validation-command openspec validate my-change --strict \
+  --adapter opencode \
+  --model-chain mimo-v2.5 minimax-3
+```
+
+The default prompt is intentionally short. It asks the agent to read the
+configured task and handoff files, implement one task, update state, and stop
+when blocked. Override it with `--prompt-template` when a project needs a
+different instruction contract.
+
+## Dry-run and machine output
+
+Preview a single command without executing it:
+
+```bash
+sisyphusfy --dry-run -- echo "hello world"
+```
+
+Preview the loop and hooks:
+
+```bash
+sisyphusfy loop --dry-run \
+  --task-path TASKS.md \
+  --completion-strategy markdown \
+  --adapter opencode \
+  --model-chain mimo-v2.5
+```
+
+Use `--json` for automation and CI consumers.
+
+## Optional completion hooks
+
+Archive and commit hooks are disabled by default. Enable them only after
+verification, and always provide an explicit commit allowlist:
+
+```bash
+sisyphusfy loop \
+  --task-path openspec/changes/my-change/tasks.md \
+  --workflow-type openspec \
+  --workflow-change-dir openspec/changes/my-change \
+  --workflow-validation-command openspec validate my-change --strict \
+  --adapter opencode \
+  --archive-command openspec archive my-change -y \
+  --commit-command git commit -m "feat: complete my change" \
+  --commit-allowed-files src README.md
+```
+
+Review the dry-run output before enabling these hooks. Sisyphusfy does not
+provide automatic push support.
+
+## Programmatic usage
+
+```python
+from sisyphusfy.runner import run_agent
+from sisyphusfy.result import Classification
+
+result = run_agent(
+    ["python3", "script.py"],
+    working_directory="/path/to/project",
+    prompt="do the thing",
+    timeout=30.0,
+    env={"API_KEY": "abc123"},
+)
+
+if result.classification == Classification.SUCCESS:
+    print("Done:", result.stdout)
+else:
+    print("Failed:", result.classification.value)
+```
+
+## Development
+
+Development is tracked with OpenSpec. See `openspec/changes/` for active work and `openspec/specs/` for accepted capability specifications.
+
+```bash
+openspec list
+openspec list
+openspec validate --all --strict
+```
+
+The repository is initialized for both OpenCode and CodeBuddy workflows. Those integrations are development conveniences; the product itself remains agent-neutral.
+
+## Supported release targets
+
+Installers download a prebuilt archive that matches the host platform and
+architecture. The published set is the same set CI builds, and every target is
+built on a runner whose native architecture matches the artifact label.
+
+| Platform | Architecture | CI runner |
+|----------|--------------|-----------|
+| linux | x86_64 | `ubuntu-latest` |
+| darwin | x86_64 | `macos-15-intel` |
+| darwin | aarch64 | `macos-14` |
+| win32 | x86_64 | `windows-latest` |
+
+`linux/aarch64` is deferred: it is not published because no runner in the
+current matrix produces it natively. Install with `pip install sisyphusfy` on
+that platform. The installer refuses a deferred target instead of downloading a
+mislabeled binary.
+
+## Status
+
+This repository contains the product design, roadmap, core implementation, and
+OpenSpec history. The runner, loop engine, agent adapters, workflow
+integrations, and completion hooks are implemented and tested.
+
+### Implemented capabilities
+
+- Fresh agent sessions with no conversation history carry-over.
+- Durable iteration loop with configurable completion, verification, and timeout.
+- OpenCode adapter (`opencode run --model <model>`), CodeBuddy adapter (`codebuddy -p`), and generic command adapter.
+- Model-chain fallback with retryable/non-retryable failure classification.
+- Workflow adapters: Markdown checklists, JSON predicates, external commands, OpenSpec tasks.
+- Configurable blocked-signal detection across stdout and stderr.
+- Opt-in archive and commit hooks with explicit file allowlists.
+- Default token-efficient prompt when no custom template is configured.
+- Human-friendly CLI: `init`, `run`, `resume`, `status`, `doctor` subcommands.
+- Project configuration in `.sisyphusfy.toml` with documented precedence.
+- Automatic OpenSpec change discovery and task/handoff file detection.
+- Human-readable progress, fallback, blocker, and next-action output.
+
+## Name
+
+Sisyphus is the figure from Greek mythology condemned to repeatedly push a boulder uphill. Sisyphusfy turns that image into a practical engineering loop: repeated work is allowed, but durable state makes each attempt advance the project.
+
+## License
+
+Sisyphusfy is released under the [MIT License](LICENSE).

sisyphusfy-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sisyphusfy"
+description = "Project-agnostic supervisor for disposable AI-agent sessions"
+requires-python = ">=3.10"
+dependencies = []
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pyyaml>=6.0"]
+
+[project.scripts]
+sisyphusfy = "sisyphusfy.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "sisyphusfy.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sisyphusfy-0.1.0/setup.cfg

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

sisyphusfy-0.1.0/src/sisyphusfy/__init__.py

@@ -0,0 +1,6 @@
+"""Sisyphusfy: project-agnostic supervisor for disposable AI-agent sessions."""
+
+# Single source of truth for the release version. pyproject.toml reads it
+# dynamically, and tests/test_version_sync.py enforces that every other
+# artifact (npm manifest, npm launcher, installers) agrees with it.
+__version__ = "0.1.0"

sisyphusfy-0.1.0/src/sisyphusfy/adapters.py

@@ -0,0 +1,221 @@
+"""Agent adapter protocol, registry, and built-in implementations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+
+class FailureClass(str, Enum):
+    RETRYABLE_PROVIDER = "retryable_provider"
+    RETRYABLE_PROCESS = "retryable_process"
+    NON_RETRYABLE = "non_retryable"
+
+
+@runtime_checkable
+class AgentAdapter(Protocol):
+    def build_command(
+        self,
+        working_directory: str,
+        prompt: str | None = None,
+    ) -> list[str]: ...
+
+    def supports_model(self, model: str) -> bool: ...
+
+    def classify_failure(self, exit_status: int, stderr: str) -> FailureClass: ...
+
+
+@dataclass
+class AdapterConfig:
+    name: str
+    model: str | None = None
+    command: list[str] = field(default_factory=list)
+
+
+class AdapterError(Exception):
+    pass
+
+
+class ModelChainExhausted(Exception):
+    def __init__(self, model_chain: list[str], attempts: list[str]) -> None:
+        self.model_chain = model_chain
+        self.attempts = attempts
+        msg = f"all models exhausted: {', '.join(attempts)}"
+        super().__init__(msg)
+
+
+_RETRYABLE_PROVIDER_MARKERS = (
+    "quota",
+    "rate_limit",
+    "rate limit",
+    "429",
+    "503",
+    "502",
+    "provider",
+    "overloaded",
+    "capacity",
+)
+
+
+class GenericCommandAdapter:
+    def __init__(
+        self,
+        command: list[str],
+        model: str | None = None,
+    ) -> None:
+        self.command = command
+        self.model = model
+
+    def build_command(
+        self,
+        working_directory: str,
+        prompt: str | None = None,
+    ) -> list[str]:
+        return list(self.command)
+
+    def supports_model(self, model: str) -> bool:
+        return True
+
+    def classify_failure(self, exit_status: int, stderr: str) -> FailureClass:
+        lower = stderr.lower()
+        for marker in _RETRYABLE_PROVIDER_MARKERS:
+            if marker in lower:
+                return FailureClass.RETRYABLE_PROVIDER
+        if exit_status == -1 or exit_status > 128:
+            return FailureClass.RETRYABLE_PROCESS
+        return FailureClass.NON_RETRYABLE
+
+
+class OpenCodeAdapter:
+    def __init__(self, model: str | None = None) -> None:
+        self.model = model
+
+    def build_command(
+        self,
+        working_directory: str,
+        prompt: str | None = None,
+    ) -> list[str]:
+        cmd = ["opencode", "run"]
+        if self.model:
+            cmd.extend(["--model", self.model])
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def supports_model(self, model: str) -> bool:
+        return True
+
+    def classify_failure(self, exit_status: int, stderr: str) -> FailureClass:
+        lower = stderr.lower()
+        for marker in _RETRYABLE_PROVIDER_MARKERS:
+            if marker in lower:
+                return FailureClass.RETRYABLE_PROVIDER
+        if exit_status == -1 or exit_status > 128:
+            return FailureClass.RETRYABLE_PROCESS
+        return FailureClass.NON_RETRYABLE
+
+
+class CodeBuddyAdapter:
+    def __init__(self, model: str | None = None) -> None:
+        self.model = model
+
+    def build_command(
+        self,
+        working_directory: str,
+        prompt: str | None = None,
+    ) -> list[str]:
+        cmd = ["codebuddy", "-p"]
+        if self.model:
+            cmd.extend(["--model", self.model])
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def supports_model(self, model: str) -> bool:
+        return True
+
+    def classify_failure(self, exit_status: int, stderr: str) -> FailureClass:
+        lower = stderr.lower()
+        for marker in _RETRYABLE_PROVIDER_MARKERS:
+            if marker in lower:
+                return FailureClass.RETRYABLE_PROVIDER
+        if exit_status == -1 or exit_status > 128:
+            return FailureClass.RETRYABLE_PROCESS
+        return FailureClass.NON_RETRYABLE
+
+
+_BUILTIN_ADAPTERS: dict[str, type] = {
+    "opencode": OpenCodeAdapter,
+    "codebuddy": CodeBuddyAdapter,
+    "generic": GenericCommandAdapter,
+}
+
+
+class AdapterRegistry:
+    def __init__(self) -> None:
+        self._adapters: dict[str, type] = dict(_BUILTIN_ADAPTERS)
+
+    def register(self, name: str, adapter_cls: type) -> None:
+        self._adapters[name] = adapter_cls
+
+    def get(self, name: str) -> type | None:
+        return self._adapters.get(name)
+
+    def list_names(self) -> list[str]:
+        return sorted(self._adapters.keys())
+
+
+def resolve_adapter(
+    config: AdapterConfig,
+    agent_command: list[str] | None = None,
+    registry: AdapterRegistry | None = None,
+) -> AgentAdapter:
+    reg = registry or AdapterRegistry()
+    cls = reg.get(config.name)
+    if cls is None:
+        raise AdapterError(
+            f"unknown adapter: {config.name!r} "
+            f"(available: {', '.join(reg.list_names())})"
+        )
+    if config.name == "generic":
+        command = config.command if config.command else (agent_command or [])
+        return GenericCommandAdapter(command=command, model=config.model)
+    return cls(model=config.model)
+
+
+def try_fallback(
+    adapter: AgentAdapter,
+    model_chain: list[str],
+    working_directory: str,
+    prompt: str | None,
+    run_fn,
+    *,
+    max_retries: int = 0,
+) -> tuple[object, list[str]]:
+    attempts: list[str] = []
+
+    models = model_chain if model_chain else [adapter.model or "default"]
+
+    for model in models:
+        if not adapter.supports_model(model):
+            continue
+        attempts.append(model)
+        result = run_fn(model=model)
+
+        raw_exit = getattr(result, "exit_status", None)
+        exit_status = raw_exit if raw_exit is not None else -1
+        stderr = getattr(result, "stderr", "") or ""
+        classification = adapter.classify_failure(exit_status, stderr)
+
+        if exit_status == 0:
+            return result, attempts
+        if classification == FailureClass.NON_RETRYABLE:
+            return result, attempts
+        if classification == FailureClass.RETRYABLE_PROVIDER:
+            continue
+        if classification == FailureClass.RETRYABLE_PROCESS:
+            continue
+        return result, attempts
+
+    raise ModelChainExhausted(model_chain=model_chain, attempts=attempts)