mcp_tool_costs.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  1. """Declared per-tool MCP costs and the per-chat spend tally behind the budget gate.
  2. A server may declare what its tools spend (``tool_costs`` in config.yaml, ``costs`` in a portable
  3. package) and a ``spend_limit`` per chat. The approval prompt then names the cost and the chat's
  4. running total, and a call that would take the chat past the limit needs an explicit yes even on a
  5. ``trust: full`` server. Figures are the server's own declared estimates: Hermes counts the declared
  6. figure (the top of a range) for every call it dispatched, never a vendor's bill.
  7. Undeclared and zero-cost tools never reach any of this, so a server without a table behaves
  8. exactly as before.
  9. """
  10. from __future__ import annotations
  11. import math
  12. import threading
  13. from contextlib import contextmanager
  14. from contextvars import ContextVar, Token
  15. from dataclasses import dataclass
  16. from typing import Any, Iterator, Mapping, Optional
  17. DEFAULT_UNIT = "credits"
  18. # Native ``mcp_servers.<name>`` keys; a portable package's ``costs`` maps to ``tool_costs``.
  19. CONFIG_KEYS = ("tool_costs", "spend_limit", "cost_unit")
  20. @dataclass(frozen=True)
  21. class ToolCost:
  22. low: float
  23. high: float
  24. note: str = ""
  25. @dataclass(frozen=True)
  26. class CostPolicy:
  27. costs: Mapping[str, ToolCost]
  28. limit: float # 0 = no limit
  29. unit: str
  30. def _number(value: Any, where: str) -> float:
  31. if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
  32. raise ValueError(f"{where} must be a non-negative number, not {value!r}")
  33. return float(value)
  34. def _parse_cost(value: Any, where: str) -> ToolCost:
  35. note = ""
  36. if isinstance(value, dict):
  37. if "credits" not in value or set(value) - {"credits", "note"}:
  38. raise ValueError(f"{where} must be a number, [min, max], or {{\"credits\": ..., \"note\": \"...\"}}")
  39. note = value.get("note", "")
  40. if not isinstance(note, str):
  41. raise ValueError(f"{where} note must be a string")
  42. value = value["credits"]
  43. if isinstance(value, (list, tuple)):
  44. if len(value) != 2:
  45. raise ValueError(f"{where} range must be [min, max]")
  46. low, high = _number(value[0], where), _number(value[1], where)
  47. if low > high:
  48. raise ValueError(f"{where} range must be [min, max] with min <= max")
  49. return ToolCost(low, high, note.strip())
  50. amount = _number(value, where)
  51. return ToolCost(amount, amount, note.strip())
  52. def parse_cost_policy(costs: Any = None, spend_limit: Any = None, cost_unit: Any = None, *,
  53. where: str) -> Optional[CostPolicy]:
  54. """Validate one server's declaration. None when it declares no tool cost (a limit alone has
  55. nothing to count); raises ValueError naming the bad key otherwise, never a silent pass."""
  56. if costs is not None and not isinstance(costs, dict):
  57. raise ValueError(f"{where} costs must be an object mapping MCP tool names to costs")
  58. table: dict[str, ToolCost] = {}
  59. for tool, value in (costs or {}).items():
  60. if not isinstance(tool, str) or not tool:
  61. raise ValueError(f"{where} costs keys must be non-empty MCP tool names")
  62. table[tool] = _parse_cost(value, f"{where} cost of '{tool}'")
  63. limit = 0.0 if spend_limit is None else _number(spend_limit, f"{where} spend_limit")
  64. unit = DEFAULT_UNIT if cost_unit is None else cost_unit
  65. if not isinstance(unit, str) or not unit.strip() or len(unit) > 32:
  66. raise ValueError(f"{where} cost_unit must be a short non-empty label, not {cost_unit!r}")
  67. if not any(cost.high > 0 for cost in table.values()):
  68. return None
  69. return CostPolicy(table, limit, unit.strip())
  70. def config_cost_policy(server_name: str, config: Mapping[str, Any] | None) -> Optional[CostPolicy]:
  71. """Policy of a native/translated ``mcp_servers`` entry (raises ValueError when malformed)."""
  72. config = config or {}
  73. return parse_cost_policy(config.get("tool_costs"), config.get("spend_limit"), config.get("cost_unit"),
  74. where=f"MCP server '{server_name}'")
  75. def _fmt(amount: float) -> str:
  76. return f"{int(amount):,}" if float(amount).is_integer() else f"{amount:,.2f}".rstrip("0").rstrip(".")
  77. def _qty(amount: float, unit: str) -> str:
  78. """``1 credit``, ``5 credits``: a plural unit label loses its ``s`` for exactly one."""
  79. return f"{_fmt(amount)} {unit[:-1] if amount == 1 and unit.endswith('s') else unit}"
  80. # Spend per (policy key, approval session key): the policy key carries the profile scope under a
  81. # multiplexer and the session key is the chat the approval system already isolates. In memory only and
  82. # never evicted: a forgotten total would hand a chat that already spent its limit a fresh budget.
  83. _lock = threading.Lock()
  84. _spent: dict[tuple, float] = {}
  85. # One budget prompt at a time per tally: a parallel call must see the total the previous approval booked,
  86. # and identical prompts would otherwise coalesce into one answer that releases several charges.
  87. _ask_locks: dict[tuple, threading.Lock] = {}
  88. # A cron run has no chat: its approval session key is "" for every job, so the scheduler binds the run's own
  89. # id here and each run gets its own tally instead of every job in the process sharing one.
  90. _run_key: ContextVar[str] = ContextVar("mcp_cost_run_key", default="")
  91. def bind_run(run_id: str) -> Token:
  92. return _run_key.set(run_id)
  93. def unbind_run(token: Token) -> None:
  94. _run_key.reset(token)
  95. def transfer_session(old_key: str, new_key: str) -> None:
  96. """The chat continues under a new session id (compression rotation, /branch): its totals move with it,
  97. or the rotation would hand a chat that already spent its limit a fresh budget."""
  98. if not old_key or not new_key or old_key == new_key:
  99. return
  100. with _lock:
  101. for key in [k for k in _spent if k[1] == old_key]:
  102. moved = (key[0], new_key)
  103. _spent[moved] = _spent.get(moved, 0.0) + _spent.pop(key)
  104. _unscoped_moved_to: Optional[str] = None # set once the process starts multiplexing
  105. def rekey_unscoped(scope: str) -> None:
  106. """Follow ``mcp_tool_scope.rekey_unscoped_connections``: a process that starts multiplexing moves its
  107. bare-name policies under ``(scope, name)``, and the chats' totals must move with them. A charge built
  108. before the move (booked or refunded after it) resolves to the moved key too."""
  109. global _unscoped_moved_to
  110. with _lock:
  111. _unscoped_moved_to = scope
  112. for key in [k for k in _spent if isinstance(k[0], str)]:
  113. amount = _spent.pop(key)
  114. _spent[_live(key)] = _spent.get(_live(key), 0.0) + amount
  115. for key in [k for k in _ask_locks if isinstance(k[0], str)]:
  116. _ask_locks.setdefault(_live(key), _ask_locks.pop(key))
  117. def _live(key: tuple) -> tuple:
  118. policy_key, session_key = key
  119. if isinstance(policy_key, str) and _unscoped_moved_to is not None:
  120. return (_unscoped_moved_to, policy_key), session_key
  121. return key
  122. @dataclass(frozen=True)
  123. class Charge:
  124. """One costed call about to be admitted: what it costs and whose tally it lands on."""
  125. key: tuple
  126. server: str
  127. tool: str
  128. cost: ToolCost
  129. policy: CostPolicy
  130. def spent(self) -> float:
  131. with _lock:
  132. return _spent.get(_live(self.key), 0.0)
  133. def over_limit(self, spent: float) -> bool:
  134. return self.policy.limit > 0 and spent + self.cost.high > self.policy.limit
  135. def reserve_within_limit(self) -> tuple[bool, float]:
  136. """Book the estimate when it keeps the chat within its limit; ``(booked, spent before)``.
  137. Check and book share the lock, so parallel calls cannot both slip under the limit."""
  138. with _lock:
  139. spent = _spent.get(_live(self.key), 0.0)
  140. if self.over_limit(spent):
  141. return False, spent
  142. self._add_locked(self.cost.high)
  143. return True, spent
  144. def book(self) -> None:
  145. with _lock:
  146. self._add_locked(self.cost.high)
  147. def refund(self) -> None:
  148. with _lock:
  149. self._add_locked(-self.cost.high)
  150. def _add_locked(self, amount: float) -> None:
  151. key = _live(self.key)
  152. _spent[key] = max(0.0, _spent.get(key, 0.0) + amount)
  153. @contextmanager
  154. def asking(self) -> Iterator[None]:
  155. """Hold this chat's budget-prompt slot while asking and booking."""
  156. with _lock:
  157. slot = _ask_locks.setdefault(_live(self.key), threading.Lock())
  158. with slot:
  159. yield
  160. def cost_sentence(self) -> str:
  161. unit, cost = self.policy.unit, self.cost
  162. text = (f"Costs about {_qty(cost.high, unit)}" if cost.low == cost.high
  163. else f"Costs {_fmt(cost.low)}-{_qty(cost.high, unit)}")
  164. return f"{text} ({cost.note})." if cost.note else f"{text}."
  165. def spend_sentence(self, spent: float) -> str:
  166. unit, limit = self.policy.unit, self.policy.limit
  167. if spent > 0:
  168. cap = f" (limit {_fmt(limit)})" if limit > 0 else ""
  169. return f"This chat has used about {_qty(spent, unit)} on '{self.server}'{cap}."
  170. return f"Spend limit for this chat on '{self.server}': {_qty(limit, unit)}." if limit > 0 else ""
  171. def lines(self, spent: float) -> list[str]:
  172. return [s for s in (self.cost_sentence(), self.spend_sentence(spent)) if s]
  173. def refusal(self, spent: float) -> str:
  174. unit = self.policy.unit
  175. return (f"MCP tool '{self.tool}' on server '{self.server}' was NOT run: this chat has used about "
  176. f"{_qty(spent, unit)} on '{self.server}' and its spend limit is {_qty(self.policy.limit, unit)}. "
  177. f"This call (about {_qty(self.cost.high, unit)}) needed an explicit approval and did not get "
  178. f"one. Do not retry; tell the user the spend limit was reached.")
  179. def pending_charge(policy_key: Any, server_name: str, tool_name: str, session_key: str) -> Optional[Charge]:
  180. """The charge a call to *tool_name* would add, or None for an undeclared/zero-cost tool."""
  181. from tools.mcp_tool_common import _core
  182. policy = _core._server_cost_policies.get(policy_key)
  183. if policy is None:
  184. return None
  185. cost = policy.costs.get(tool_name)
  186. if cost is None or cost.high <= 0:
  187. return None
  188. return Charge((policy_key, _run_key.get() or session_key), server_name, tool_name, cost, policy)
  189. def unknown_cost_keys(policy: Optional[CostPolicy], tool_names: list[str]) -> list[str]:
  190. """Declared tool names the server does not offer: a typo, or Hermes' ``mcp_<server>_`` display prefix
  191. copied into the table. Those tools would run with no cost and no budget, so registration warns."""
  192. if policy is None or not tool_names:
  193. return []
  194. offered = set(tool_names)
  195. return sorted(k for k in policy.costs if k not in offered)