Skip to content

The agent that grows with you

fix(mcp): spend totals survive session rotation; each cron run has its own; review fixes

Tekniumce18aafe010c
diff --git a/cron/scheduler.py b/cron/scheduler.py
index 2ee2511ef2a..80182d13e52 100644
--- a/cron/scheduler.py
+++ b/cron/scheduler.py
@@ -2390,6 +2390,7 @@ class _CronRunScope:
self._cron_session_var = _VAR_MAP["HERMES_CRON_SESSION"]
self._cron_session_token = None
self._non_dispatcher_token = None
+ self._spend_token = None
def enter(self) -> None:
# Scope cron approval policy; exit() RESETS via token (pinning "" would suppress the legacy
@@ -2400,6 +2401,9 @@ class _CronRunScope:
# ContextVar, NOT an os.environ clear (env is shared with the worker heartbeat and
# concurrent jobs); copy_context() carries it into the agent thread.
self._non_dispatcher_token = enter_non_dispatcher_owned_context()
+ # Each run is its own MCP spend "chat" (its approval session key is "" for every job).
+ from tools.mcp_tool_costs import bind_run
+ self._spend_token = bind_run(self.task_id)
def exit(self) -> None:
from gateway.session_context import clear_session_vars
@@ -2411,6 +2415,9 @@ class _CronRunScope:
self._cron_session_var.reset(self._cron_session_token)
if self._non_dispatcher_token is not None:
exit_non_dispatcher_owned_context(self._non_dispatcher_token)
+ if self._spend_token is not None:
+ from tools.mcp_tool_costs import unbind_run
+ unbind_run(self._spend_token)
for name in _CRON_DELIVERY_VARS:
self._var_map[name].set("")
diff --git a/tests/tools/test_mcp_tool_costs.py b/tests/tools/test_mcp_tool_costs.py
index e0bb1c3f667..8faa3e773f7 100644
--- a/tests/tools/test_mcp_tool_costs.py
+++ b/tests/tools/test_mcp_tool_costs.py
@@ -2,8 +2,10 @@
Invariants: a costed call's prompt names the cost and the chat's running total; only dispatched
calls count; a call that would cross ``spend_limit`` asks even on a ``trust: full`` server and is
-refused unattended without dispatching; chats and profiles never share a tally; malformed
-declarations fail with a named error (package and config.yaml) while unknown keys only warn.
+refused unattended without dispatching; chats and profiles never share a tally, a chat keeps its
+total across a session-id rotation and each cron run has its own; parallel over-limit calls are asked
+one at a time; malformed declarations fail with a named error (package and config.yaml) while unknown
+keys only warn.
"""
import asyncio
@@ -48,6 +50,7 @@ def session():
patch.dict(mcp_tool._tool_read_only_hints, {}, clear=True), \
patch.dict(mcp_tool._server_cost_policies, {}, clear=True), \
patch.dict(mcp_tool_costs._spent, {}, clear=True), \
+ patch.dict(mcp_tool_costs._ask_locks, {}, clear=True), \
patch.object(mcp_tool_costs, "_unscoped_moved_to", None):
yield session
@@ -168,3 +171,69 @@ def test_declarations_validate_translate_and_survive_a_native_trust_override(tmp
# A native entry rejected for a malformed budget is not revived by the package's looser one.
with patch("hermes_cli.config.load_config", return_value={"mcp_servers": {"srv": {"command": "x", "spend_limit": -5}}}):
assert "srv" not in _load_mcp_config()
+
+
+def test_a_chat_keeps_its_total_across_a_rotation_and_each_cron_run_has_its_own(session, caplog):
+ from cron.scheduler import _CronRunScope
+ from gateway.session_context import clear_session_vars, set_session_vars
+ with caplog.at_level("WARNING", logger="tools.mcp_tool"):
+ _register(dict(COSTED, tool_costs={**COSTED["tool_costs"], "mcp_srv_typo": 3}))
+ assert "mcp_srv_typo" in caplog.text # a key the server does not offer is named, never silently dropped
+ for _ in range(2):
+ _call("paid_render", chat="parent")
+ # Compression (CLI, TUI/Desktop) and /branch continue the chat under a new id through this one hook.
+ from tools.approval_yolo import transfer_session_yolo
+ transfer_session_yolo("parent", "child")
+ assert "used about 80 credits" in _call("paid_render", chat="child", answer="decline")[1][0]
+ # Cron: the approval session key is "" for every job; each run binds its own tally.
+ tokens = set_session_vars(cron_session="1")
+ try:
+ for job in ("job-a", "job-b", "job-c"):
+ scope = _CronRunScope({}, job, "run-1")
+ scope.enter()
+ try:
+ token = set_current_session_key("")
+ try:
+ for _ in range(2):
+ assert json.loads(handlers._make_tool_handler("srv", "paid_render", 30.0)({})) == {"result": "ok"}
+ finally:
+ reset_current_session_key(token)
+ finally:
+ scope.exit()
+ finally:
+ clear_session_vars(tokens)
+
+
+def test_parallel_over_limit_calls_are_asked_one_at_a_time(session):
+ import threading
+ _register(COSTED)
+ for _ in range(2):
+ _call("paid_render") # 80 of 100: the next two parallel calls both cross the limit
+ open_prompts, peak, prompts, gate = [0], [0], [], threading.Barrier(2, timeout=2)
+
+ def consent(msg, desc, **kw):
+ open_prompts[0] += 1
+ peak[0] = max(peak[0], open_prompts[0])
+ prompts.append(msg)
+ try:
+ gate.wait() # unserialized prompts would meet here; serialized ones time out alone
+ except threading.BrokenBarrierError:
+ pass
+ open_prompts[0] -= 1
+ return "accept"
+
+ def one():
+ token = set_current_session_key("chat-a")
+ try:
+ handlers._make_tool_handler("srv", "paid_render", 30.0)({})
+ finally:
+ reset_current_session_key(token)
+
+ with patch("tools.approval_prompt.request_elicitation_consent", side_effect=consent):
+ threads = [threading.Thread(target=one) for _ in range(2)]
+ for th in threads:
+ th.start()
+ for th in threads:
+ th.join(10)
+ assert peak[0] == 1 and len(prompts) == 2
+ assert {"used about 80 credits" in p for p in prompts} == {True, False} # the second saw the first's booking
diff --git a/tools/approval_yolo.py b/tools/approval_yolo.py
index 948c3d92642..0059ddc4418 100644
--- a/tools/approval_yolo.py
+++ b/tools/approval_yolo.py
@@ -92,7 +92,11 @@ def restore_gateway_yolo(session_key: str, persisted: Optional[bool], *, launch:
def transfer_session_yolo(old_key: str, new_key: str) -> None:
"""Move the live bypass when the conversation continues under a new id (compression rotation, /branch).
- The new row records it at creation (``with_session_yolo``), so nothing is written here."""
+ The new row records it at creation (``with_session_yolo``), so nothing is written here. Every
+ continuation site calls this, so it also moves the chat's MCP spend total: a rotation must not hand a
+ chat that spent its limit a fresh budget."""
+ from tools.mcp_tool_costs import transfer_session
+ transfer_session(old_key, new_key)
if not old_key or not new_key or old_key == new_key or not approval.is_session_yolo_enabled(old_key):
return
approval.enable_session_yolo(new_key)
diff --git a/tools/mcp_tool_costs.py b/tools/mcp_tool_costs.py
index b0bf9f61702..a802421d345 100644
--- a/tools/mcp_tool_costs.py
+++ b/tools/mcp_tool_costs.py
@@ -14,8 +14,9 @@ from __future__ import annotations
import math
import threading
-from dataclasses import dataclass
from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
from typing import Any, Iterator, Mapping, Optional
DEFAULT_UNIT = "credits"
@@ -94,6 +95,11 @@ def _fmt(amount: float) -> str:
return f"{int(amount):,}" if float(amount).is_integer() else f"{amount:,.2f}".rstrip("0").rstrip(".")
+def _qty(amount: float, unit: str) -> str:
+ """``1 credit``, ``5 credits``: a plural unit label loses its ``s`` for exactly one."""
+ return f"{_fmt(amount)} {unit[:-1] if amount == 1 and unit.endswith('s') else unit}"
+
+
# Spend per (policy key, approval session key): the policy key carries the profile scope under a
# multiplexer and the session key is the chat the approval system already isolates. In memory only and
# never evicted: a forgotten total would hand a chat that already spent its limit a fresh budget.
@@ -102,6 +108,28 @@ _spent: dict[tuple, float] = {}
# One budget prompt at a time per tally: a parallel call must see the total the previous approval booked,
# and identical prompts would otherwise coalesce into one answer that releases several charges.
_ask_locks: dict[tuple, threading.Lock] = {}
+# A cron run has no chat: its approval session key is "" for every job, so the scheduler binds the run's own
+# id here and each run gets its own tally instead of every job in the process sharing one.
+_run_key: ContextVar[str] = ContextVar("mcp_cost_run_key", default="")
+
+
+def bind_run(run_id: str) -> Token:
+ return _run_key.set(run_id)
+
+
+def unbind_run(token: Token) -> None:
+ _run_key.reset(token)
+
+
+def transfer_session(old_key: str, new_key: str) -> None:
+ """The chat continues under a new session id (compression rotation, /branch): its totals move with it,
+ or the rotation would hand a chat that already spent its limit a fresh budget."""
+ if not old_key or not new_key or old_key == new_key:
+ return
+ with _lock:
+ for key in [k for k in _spent if k[1] == old_key]:
+ moved = (key[0], new_key)
+ _spent[moved] = _spent.get(moved, 0.0) + _spent.pop(key)
_unscoped_moved_to: Optional[str] = None # set once the process starts multiplexing
@@ -117,6 +145,8 @@ def rekey_unscoped(scope: str) -> None:
for key in [k for k in _spent if isinstance(k[0], str)]:
amount = _spent.pop(key)
_spent[_live(key)] = _spent.get(_live(key), 0.0) + amount
+ for key in [k for k in _ask_locks if isinstance(k[0], str)]:
+ _ask_locks.setdefault(_live(key), _ask_locks.pop(key))
def _live(key: tuple) -> tuple:
@@ -174,16 +204,16 @@ class Charge:
def cost_sentence(self) -> str:
unit, cost = self.policy.unit, self.cost
- text = (f"Costs about {_fmt(cost.high)} {unit}" if cost.low == cost.high
- else f"Costs {_fmt(cost.low)}-{_fmt(cost.high)} {unit}")
+ text = (f"Costs about {_qty(cost.high, unit)}" if cost.low == cost.high
+ else f"Costs {_fmt(cost.low)}-{_qty(cost.high, unit)}")
return f"{text} ({cost.note})." if cost.note else f"{text}."
def spend_sentence(self, spent: float) -> str:
unit, limit = self.policy.unit, self.policy.limit
if spent > 0:
cap = f" (limit {_fmt(limit)})" if limit > 0 else ""
- return f"This chat has used about {_fmt(spent)} {unit} on '{self.server}'{cap}."
- return f"Spend limit for this chat on '{self.server}': {_fmt(limit)} {unit}." if limit > 0 else ""
+ return f"This chat has used about {_qty(spent, unit)} on '{self.server}'{cap}."
+ return f"Spend limit for this chat on '{self.server}': {_qty(limit, unit)}." if limit > 0 else ""
def lines(self, spent: float) -> list[str]:
return [s for s in (self.cost_sentence(), self.spend_sentence(spent)) if s]
@@ -191,8 +221,8 @@ class Charge:
def refusal(self, spent: float) -> str:
unit = self.policy.unit
return (f"MCP tool '{self.tool}' on server '{self.server}' was NOT run: this chat has used about "
- f"{_fmt(spent)} {unit} on '{self.server}' and its spend limit is {_fmt(self.policy.limit)} {unit}. "
- f"This call (about {_fmt(self.cost.high)} {unit}) needed an explicit approval and did not get "
+ f"{_qty(spent, unit)} on '{self.server}' and its spend limit is {_qty(self.policy.limit, unit)}. "
+ f"This call (about {_qty(self.cost.high, unit)}) needed an explicit approval and did not get "
f"one. Do not retry; tell the user the spend limit was reached.")
@@ -205,4 +235,13 @@ def pending_charge(policy_key: Any, server_name: str, tool_name: str, session_ke
cost = policy.costs.get(tool_name)
if cost is None or cost.high <= 0:
return None
- return Charge((policy_key, session_key), server_name, tool_name, cost, policy)
+ return Charge((policy_key, _run_key.get() or session_key), server_name, tool_name, cost, policy)
+
+
+def unknown_cost_keys(policy: Optional[CostPolicy], tool_names: list[str]) -> list[str]:
+ """Declared tool names the server does not offer: a typo, or Hermes' ``mcp_<server>_`` display prefix
+ copied into the table. Those tools would run with no cost and no budget, so registration warns."""
+ if policy is None or not tool_names:
+ return []
+ offered = set(tool_names)
+ return sorted(k for k in policy.costs if k not in offered)
diff --git a/tools/mcp_tool_handlers.py b/tools/mcp_tool_handlers.py
index fcde468db09..b93fb3b03ea 100644
--- a/tools/mcp_tool_handlers.py
+++ b/tools/mcp_tool_handlers.py
@@ -101,7 +101,8 @@ def _ask_for_call(server_name: str, tool_name: str, charge, booked: Optional[lis
if gated:
head = f"MCP tool '{tool_name}' on UNTRUSTED server '{server_name}' wants to run."
tail = "This tool is write-capable (no readOnlyHint=true annotation) and may modify external state."
- message = " ".join([head, *extra, *(["This call goes past the chat's spend limit."] if over else []), tail])
+ # The limit notice leads: the messaging gateway's text fallback keeps only the first ~200 characters.
+ message = " ".join([head, *(["This call goes past the chat's spend limit."] if over else []), *extra, tail])
description = (f"Server '{server_name}' is configured 'trust: untrusted'. "
f"Approve to run '{tool_name}' once, or deny to block it.")
title = f"MCP server '{server_name}' is asking"
diff --git a/tools/mcp_tool_registration.py b/tools/mcp_tool_registration.py
index f7b6ec9a608..d8991f9a02d 100644
--- a/tools/mcp_tool_registration.py
+++ b/tools/mcp_tool_registration.py
@@ -82,6 +82,15 @@ def _record_tool_trust_metadata(server_name: str, config: dict, tools: list[Any]
_record_cost_policy(server_name, config, key)
hints = _core._tool_read_only_hints.setdefault(key, {})
hints.update({t.name: _annotation_read_only_hint(t) for t in tools if getattr(t, "name", None)})
+ _warn_unknown_cost_keys(server_name, key, [t.name for t in tools if getattr(t, "name", None)])
+
+
+def _warn_unknown_cost_keys(server_name: str, key, tool_names: list[str]) -> None:
+ from tools.mcp_tool_costs import unknown_cost_keys
+ if unknown := unknown_cost_keys(_core._server_cost_policies.get(key), tool_names):
+ logger.warning("MCP server '%s': tool_costs names %s, which the server does not offer, so those calls "
+ "carry no cost and no spend limit. Use the server's own tool names (without Hermes' "
+ "'mcp_%s_' prefix).", server_name, unknown, server_name)
def _record_scope_trust(server_name: str, config: dict, scope: str) -> None:
diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.md
index d20461a93fd..f2d6d1623a7 100644
--- a/website/docs/developer-guide/plugins/index.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -143,7 +143,8 @@ call to that server that is not annotated `readOnlyHint: true` asks the user
first, and fails closed where nobody can answer (cron, unattended runs). The
only other accepted value is `full`, the default, so a package can narrow
access but never widen it. A `config.yaml` server with the same name replaces
-the package's entry, including its trust. Other harnesses ignore this extension.
+the package's entry, including its trust, but keeps the package's declared costs
+and spend limit (below) unless it sets its own. Other harnesses ignore this extension.
`trust` can sit beside `app`, `requires` and `liveness` in the same server
entry (see [Application declarations](./application-declarations.md)).
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index ad8a033ac06..4c567fb6c92 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -998,10 +998,11 @@ mcp_servers:
```
- The approval prompt names the cost: `Costs about 20 credits.` or `Costs 5-20 credits (per animation).`, plus `This chat has used about 40 credits on 'renders' (limit 100).` once the chat has spent something.
-- Hermes keeps a running total per chat and per server, counting the declared figure (the top of a range) for every costed call it actually sent. Declined or blocked calls add nothing. The total lives in memory: it is a budget for one conversation, not the vendor's bill.
+- Hermes keeps a running total per chat and per server, counting the declared figure (the top of a range) for every costed call it approved and started. Declined or blocked calls add nothing; a call whose server dies before receiving it still counts, which errs toward asking sooner. The total lives in memory: it is a budget for one conversation, not the vendor's bill.
+- The total follows the conversation when context compression or `/branch` continues it under a new session id. Starting a new chat (`/new` in the CLI, a new Desktop chat) starts a new total; on messaging platforms the total belongs to the chat, so it survives `/new` there. Each cron run has its own total. Restarting Hermes resets every total.
- With `spend_limit`, a costed call that would take the chat past the limit asks first, even on a `trust: full` server that otherwise never prompts, and every further costed call in that chat asks again ("Allow for this session" does not silence it). Where nobody can answer (cron jobs, `hermes chat -q`, a gateway with no approver), the call is refused without running and the model is told not to retry.
- Below the limit, a `trust: full` server still runs costed tools without asking; on a `trust: untrusted` server every write-capable call already asks and the prompt now carries the cost. Tools annotated `readOnlyHint: true` stay unprompted unless the budget requires it.
-- A malformed `tool_costs`, `spend_limit` or `cost_unit` skips the server with an error naming the key, so a budget you declared is never silently dropped.
+- A malformed `tool_costs`, `spend_limit` or `cost_unit` skips the server with an error naming the key, so a budget you declared is never silently dropped. A `tool_costs` key the server does not offer (a typo, or Hermes' `mcp_<server>_` display prefix copied in) is named in a warning at connect time: use the server's own tool names.
A [portable plugin package](../../developer-guide/plugins/index.md#portable-agent-plugins-v1-packages) can declare the same table for its server. If you add a same-name `mcp_servers` entry (for example to set `trust: full`), the package's `tool_costs`, `spend_limit` and `cost_unit` still apply unless your entry sets those keys itself; `spend_limit: 0` turns the package's limit off and `tool_costs: {}` drops its costs.