# orchestrator/time.py
from __future__ import annotations

from datetime import datetime, timedelta, timezone

# Single canonical format for all timestamps the agent writes.
# ISO 8601, UTC, second precision, trailing "Z".
# Examples: "2026-09-21T11:45:00Z"
ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ"


def now_iso() -> str:
    """Current UTC time as an ISO 8601 string."""
    return datetime.now(timezone.utc).strftime(ISO_FORMAT)


def now_iso_plus(
    *,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
) -> str:
    """Current UTC time plus a delta, as an ISO 8601 string."""
    delta = timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
    return (datetime.now(timezone.utc) + delta).strftime(ISO_FORMAT)


def parse_iso(s: str) -> datetime:
    """Parse an ISO 8601 string produced by now_iso / now_iso_plus."""
    return datetime.strptime(s, ISO_FORMAT).replace(tzinfo=timezone.utc)