"""Declarative runtime/deployment metadata.

These types describe *how* the platform should run an agent: lifecycle,
state needs, isolation level, resource budget, egress policy. They are
read by the deployer and by the registry; agent code itself should not
depend on which runtime is selected.
"""
from __future__ import annotations

from enum import Enum

from pydantic import BaseModel, ConfigDict, Field, NonNegativeInt, PositiveInt


class Lifecycle(str, Enum):
    """How long an instance of the agent process lives."""

    EPHEMERAL = "ephemeral"  # spawned per-invocation, torn down after
    SESSION = "session"  # spawned per-session, kept until the session ends
    WARM = "warm"  # long-running service, multiplexed across callers


class State(str, Enum):
    """What kind of state the agent retains between invocations."""

    NONE = "none"  # purely functional
    SESSION = "session"  # in-memory state for the lifetime of a session
    DURABLE = "durable"  # persisted across restarts (storage required)


class Sandbox(str, Enum):
    """Isolation level. The platform always runs agents under microsandbox.

    Modeled as an enum (rather than a constant) so the wire format stays
    stable if more isolation tiers are added later, but only one value is
    currently valid: every agent runs in a microvm-class sandbox.
    """

    MICROSANDBOX = "microsandbox"


class Resources(BaseModel):
    """Resource budget hint for the deployer."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    cpu: str = "100m"  # k8s-style CPU spec, e.g. "500m", "2"
    memory: str = "256Mi"  # k8s-style memory, e.g. "512Mi", "4Gi"
    gpu: NonNegativeInt = 0
    max_runtime_seconds: PositiveInt = 600


class SkillPolicy(BaseModel):
    """Per-skill operational policy advertised on the Agent Card."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    timeout_seconds: float | None = None
    idempotent: bool = False
    max_retries: NonNegativeInt = 0
    cost_class: str | None = None  # informational, e.g. "cheap" / "expensive"


class EgressPolicy(BaseModel):
    """What external hosts the agent is allowed to talk to."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    allow_hosts: tuple[str, ...] = ()
    allow_internal_services: tuple[str, ...] = ()  # e.g. cluster service DNS
    deny_internet_by_default: bool = True


class AgentRuntime(BaseModel):
    """Aggregate runtime declaration; published on the Agent Card."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    lifecycle: Lifecycle = Lifecycle.EPHEMERAL
    state: State = State.NONE
    sandbox: Sandbox = Sandbox.MICROSANDBOX
    resources: Resources = Field(default_factory=Resources)
    concurrency: PositiveInt = 1
    egress: EgressPolicy = Field(default_factory=EgressPolicy)
    tools_used: tuple[str, ...] = ()