"""Task authoring protocol (static guidance for tasks).

Provides a Protocol to document and type-check the
interface the framework expects for task implementations.
"""

from __future__ import annotations

from typing import Protocol, runtime_checkable, Any
from hil_testbench.config.task_config import TaskConfig
from hil_testbench.task.specs import ParserDefinition


@runtime_checkable
class TaskLike(Protocol):
    """Minimal interface a task should implement.

    Required:
    - commands(config): returns a list of command objects (Command or CommandDefinition)

    Optional:
    - parser(config): returns ParserDefinition or None
    - schema: dict or ParametersSchema (attribute)
    - cli_args(argparse.ArgumentParser): classmethod for CLI flags
    - task_name: str (attribute); defaults to class name if missing
    - concurrent: bool (attribute); defaults to False
    """

    def commands(self, config: TaskConfig) -> list[Any]: ...

    def parser(self, config: TaskConfig) -> ParserDefinition | None: ...
