"""执行器基类（叶子模块，不依赖 cloud.sandbox 与 cloud.chv，
避免循环导入）。

原来在 cloud/sandbox.py 里；拆分后 Local/Docker/Cloud
执行器（sandbox.py 内）与 CloudHypervisorExecutor
（cloud/chv/executor.py）共用这一个类对象，isinstance
判断与旧路径 `from cloud.sandbox import Executor` 都不变
（sandbox.py 会 re-export 它）。
"""


class Executor:
    """执行器基类。

    task 是 dict，含 id、project_id、repo、prompt、branch（可选）。
    execute(task) -> dict，至少含 executor、task_id、status、stdout。
    """

    def execute(self, task) -> dict:
        raise NotImplementedError("子类必须实现 execute(task)")

    def goal_task(self, task) -> dict:
        """目标循环（host.py goal）：turn→验测→喂回重试。

        子类实现；默认不支持（CloudExecutor 的通用 HTTP 协议里
        没有 goal/验测概念，调它会如实失败，不静默降级成普通
        dispatch）。结果 dict 除 execute() 的字段外另含：
        goal_met（True/False/None=无结论）、goal_error。
        """
        raise NotImplementedError("该执行器不支持 goal 模式")