from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Dict, Optional

from src.core.FinanceState import FinanceState


def add_error(
    state: FinanceState,
    *,
    code: str,
    message: str,
    agent: Optional[str] = None,
    detail: Optional[Dict[str, Any]] = None,
) -> None:
    """
    Append a normalized error entry into state["errors"].

    This is best-effort telemetry for UI/debugging; it should never raise.
    """
    try:
        entry: Dict[str, Any] = {
            "ts": datetime.now(timezone.utc).isoformat(),
            "code": code,
            "message": message,
        }
        trace_id = state.get("trace_id")
        if isinstance(trace_id, str) and trace_id:
            entry["trace_id"] = trace_id
        if agent:
            entry["agent"] = agent
        if detail:
            entry["detail"] = detail

        errors = state.get("errors")
        if not isinstance(errors, list):
            errors = []
        errors.append(entry)
        state["errors"] = errors
    except Exception:
        # Never allow telemetry to break the user experience.
        return