"""工具统一返回信封

约定：成功 {"ok": true, ...data}；失败 {"ok": false, reason, detail, next_action}。
工具一律不抛异常穿透到协议层，便于宿主 Agent 读 reason 自行决策。
"""

from __future__ import annotations

from typing import Any


def ok(**data: Any) -> dict[str, Any]:
    """成功信封。"""
    return {"ok": True, **data}


def fail(reason: str, *, next_action: str = "", **detail: Any) -> dict[str, Any]:
    """失败信封。reason 必须可执行；detail 放结构化上下文。"""
    out: dict[str, Any] = {"ok": False, "reason": reason}
    if next_action:
        out["next_action"] = next_action
    if detail:
        out["detail"] = detail
    return out