"""Typed OpenEnv contracts: Action, Observation, State."""

from __future__ import annotations

from typing import Literal

from openenv.core.env_server import Action, Observation, State
from pydantic import BaseModel, ConfigDict, Field


class CacheItem(BaseModel):
    model_config = ConfigDict(extra="allow")

    key: str
    age: int = Field(ge=0)
    access_count: int = Field(ge=0)
    last_result: str


class CacheAction(Action):
    """Per-step decision for one cache key."""

    type: Literal["invalidate", "refresh", "keep"]
    key: str


class CacheObservation(Observation):
    """What the agent sees (no hidden TTL / true staleness)."""

    items: list[CacheItem] = Field(default_factory=list)
    step: int = Field(default=0, ge=0)
    task_id: str = ""
    final_score: float | None = Field(
        default=None,
        description="Episode grader output in [0,1] when done=True; else None.",
    )


class CacheState(State):
    """Server-visible state (no hidden dynamics)."""

    task_id: str = ""
    items: list[CacheItem] = Field(default_factory=list)