"""
adapters/base/runtime.py
Abstract base class for all agent-runtime adapters.
"""
from abc import ABC, abstractmethod


class RuntimeAdapter(ABC):
    """
    Contract that every agent runtime adapter must fulfil.

    A "runtime" is responsible for dispatching a task to an actual agent
    (e.g. an OpenClaw worker, a Claude Code sub-agent, a local subprocess)
    and retrieving its result.
    """

    @abstractmethod
    def spawn(self, task: str, capability: str, context: dict) -> str:
        """
        Start an agent to work on the given task.

        Parameters
        ----------
        task       : Natural-language description of the work to perform.
        capability : Capability hint — "reasoning-heavy" | "capable" | "fast-cheap".
        context    : Arbitrary key/value bag (e.g. files, constraints, brief payload).

        Returns
        -------
        A provider-specific agent_id string that can be used to poll for results.
        """
        ...

    @abstractmethod
    def get_result(self, agent_id: str, timeout_s: int) -> dict:
        """
        Block until the agent completes or the timeout elapses.

        Parameters
        ----------
        agent_id  : The id returned by spawn().
        timeout_s : Maximum seconds to wait before raising TimeoutError.

        Returns
        -------
        A dict containing at minimum:
            {
                "status":   "done" | "failed" | "partial" | "blocked",
                "output":   <str or dict>,
                "artifacts": [...],   # optional
            }
        """
        ...

    @abstractmethod
    def kill(self, agent_id: str) -> None:
        """
        Terminate a running agent unconditionally.

        Parameters
        ----------
        agent_id : The id returned by spawn().
        """
        ...