"""Enum definitions for anima schema models.

Source: extracted from `src/anima/core/schemas.py` to support package layout.
"""

from enum import Enum


class AgentState(str, Enum):
    """Agent lifecycle state.

    State machine transitions defined in docs/INTERFACES.md Section H.1.

    Terminal states: completed, failed, killed.

    >>> AgentState.pending.value
    'pending'
    >>> AgentState.running.value
    'running'
    >>> AgentState("suspended")
    <AgentState.suspended: 'suspended'>
    """

    pending = "pending"
    running = "running"
    suspended = "suspended"
    awaiting_approval = "awaiting_approval"
    completed = "completed"
    failed = "failed"
    killed = "killed"


class LifecycleType(str, Enum):
    """Agent lifecycle type.

    - ephemeral: Agent exits after task completion.
    - daemon: Agent persists for events, ignores ctl_finish.

    See docs/INTERFACES.md Section H.3 for daemon behavior.

    >>> LifecycleType.ephemeral.value
    'ephemeral'
    >>> LifecycleType.daemon.value
    'daemon'
    >>> LifecycleType("ephemeral")
    <LifecycleType.ephemeral: 'ephemeral'>
    """

    ephemeral = "ephemeral"
    daemon = "daemon"


class CompletionPolicy(str, Enum):
    """Agent completion policy.

    - explicit: Agent must call ctl_finish() to complete.
    - auto: Agent auto-completes after two consecutive turns without tool calls.

    See docs/INTERFACES.md Section D.6 for auto-completion behavior.

    >>> CompletionPolicy.explicit.value
    'explicit'
    >>> CompletionPolicy.auto.value
    'auto'
    >>> CompletionPolicy("explicit")
    <CompletionPolicy.explicit: 'explicit'>
    """

    explicit = "explicit"
    auto = "auto"


class SideEffectPolicy(str, Enum):
    """Side effect policy for tool calls.

    - allow: All tool calls permitted.
    - approval_required: Non-read-only tools require approval via ctl_request_approval.
    - read_only: Only read-only tools permitted.

    Read-only tool heuristic: tools whose names start with read, get, list,
    search, find, show, or status.

    See docs/INTERFACES.md Section E (JobSpec.side_effect_policy).

    >>> SideEffectPolicy.allow.value
    'allow'
    >>> SideEffectPolicy.approval_required.value
    'approval_required'
    >>> SideEffectPolicy.read_only.value
    'read_only'
    >>> SideEffectPolicy("allow")
    <SideEffectPolicy.allow: 'allow'>
    """

    allow = "allow"
    approval_required = "approval_required"
    read_only = "read_only"


class ToolPosture(str, Enum):
    """Per-tool override posture for persona tool permissions.

    - none: Tool is explicitly blocked.
    - read_only: Tool may run only read-only operations.
    - read_write: Tool may run read/write operations.
    - destructive: Tool may run destructive operations.

    >>> ToolPosture.none.value
    'none'
    >>> ToolPosture.read_only.value
    'read_only'
    >>> ToolPosture.read_write.value
    'read_write'
    >>> ToolPosture.destructive.value
    'destructive'
    >>> ToolPosture("read_only")
    <ToolPosture.read_only: 'read_only'>
    """

    none = "none"
    read_only = "read_only"
    read_write = "read_write"
    destructive = "destructive"


POSTURE_RANK: dict[ToolPosture, int] = {
    ToolPosture.none: 0,
    ToolPosture.read_only: 1,
    ToolPosture.read_write: 2,
    ToolPosture.destructive: 3,
}


class ContextMode(str, Enum):
    """Context sharing mode for sub-agents.

    - isolated: Agent starts with fresh context.
    - shared: Agent inherits parent context via ContextBundle.

    >>> ContextMode.isolated.value
    'isolated'
    >>> ContextMode.shared.value
    'shared'
    >>> ContextMode("isolated")
    <ContextMode.isolated: 'isolated'>
    """

    isolated = "isolated"
    shared = "shared"
