bot_chain.py 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. """Bot-to-bot chains in Bot Mode: a runtime-owned hop count, identical-ask dedupe and the reply rule.
  2. A human message starts a chain. Inside a bot-authored turn every ``message_agent`` call is one more
  3. hop (a fan-out is one call, so its targets share the hop); a person's own turn sends at hop 1. The
  4. hop number rides in the delivery's author envelope (``hops``), which only the runtime writes, so the
  5. model cannot reset it. Past ``gateway.bot_loop_guard.max_hops`` (config.yaml, the same cap the
  6. messaging gateway applies) a send is refused and nothing is delivered. The same message to the same
  7. recipient twice in one chain is refused as a duplicate. A message to the bot whose message started
  8. this turn is a reply: unless ``bot_replies_expect_reply`` is true it goes notify-only (#144789's
  9. ``[no reply needed]`` marker and ``wake="none"``), and a turn started by such a message cannot message
  10. that bot back. Each side also counts the bot turns it runs, so a lane that carries no envelope (the
  11. Desktop relay) is still capped. ``gateway.bot_loop_guard.enabled: false`` turns all of it off (#137027).
  12. Recipients are compared by the identity the receiving turn's author id carries (``bot:<profile>``,
  13. ``bot:<connection>/<profile>``), resolved by the caller with the same resolver delivery uses.
  14. """
  15. from __future__ import annotations
  16. import hashlib
  17. import threading
  18. import time
  19. from dataclasses import dataclass, field
  20. from typing import Any, Optional
  21. # Keyed by session id, not held on the agent: a gateway may rebuild the agent between turns, and a
  22. # lost count would hand the chain a fresh budget. A session id change (compression rotation, turn-start
  23. # recovery, lease reload) moves the entry along (``carry_chain`` / ``_bound_key``).
  24. _CHAINS: dict[str, dict] = {}
  25. _LOCK = threading.Lock()
  26. def _settings():
  27. from gateway.bot_loop_guard import load_settings
  28. return load_settings()
  29. def _hops(author: Optional[dict]) -> int:
  30. value = (author or {}).get("hops")
  31. return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else 0
  32. def _new_state(now: float) -> dict:
  33. return {"hops": 0, "sent": 0, "asks": set(), "no_reply_from": None, "updated": now}
  34. def _bound_key(agent: Any) -> str:
  35. """The agent's chain key, carrying the chain over when its session id moved since the last turn
  36. or send. Caller holds ``_LOCK``."""
  37. key = str(getattr(agent, "session_id", "") or id(agent))
  38. previous = getattr(agent, "_bot_chain_session", None)
  39. if previous and previous != key and previous in _CHAINS and key not in _CHAINS:
  40. _CHAINS[key] = _CHAINS.pop(previous)
  41. try:
  42. agent._bot_chain_session = key
  43. except AttributeError:
  44. pass
  45. return key
  46. def carry_chain(old_session_id: str, new_session_id: str) -> None:
  47. """Move a chain to the session id a compression rotation hands the conversation."""
  48. if not old_session_id or not new_session_id or old_session_id == new_session_id:
  49. return
  50. with _LOCK:
  51. state = _CHAINS.pop(str(old_session_id), None)
  52. if state is not None:
  53. _CHAINS.setdefault(str(new_session_id), state)
  54. def on_turn_start(agent: Any, turn_author: Optional[dict], display_kind: Optional[str],
  55. user_message: Any = None) -> None:
  56. """Set the hop this session's turn runs at. A bot-authored turn runs at the hop its envelope names
  57. (or one past this side's own count, whichever is higher); a completion wake after this bot sent a
  58. message carries the answer, which is one more hop; a person's message ends the chain. A fork
  59. (background review, side question) shares the session id but is not the conversation: no change."""
  60. if getattr(agent, "_turn_origin", None):
  61. return
  62. settings = _settings()
  63. if not settings.enabled:
  64. return
  65. from gateway.response_filters import is_machinery_display_kind
  66. from tools.bot_mode_probe import NO_REPLY_MARKER
  67. now = time.monotonic()
  68. with _LOCK:
  69. key = _bound_key(agent)
  70. for stale in [k for k, v in _CHAINS.items() if now - v["updated"] > settings.cooldown_seconds]:
  71. del _CHAINS[stale]
  72. state = _CHAINS.get(key)
  73. if isinstance(turn_author, dict) and turn_author.get("is_bot"):
  74. state = _CHAINS.setdefault(key, _new_state(now))
  75. state["hops"] = max(state["hops"] + 1, _hops(turn_author))
  76. state["sent"] = max(state["sent"], state["hops"])
  77. # The sender's notify-only marker, read from the text like gateway/session_bot_outcome.py
  78. # does, so it survives every transport (the Desktop relay rebuilds the author).
  79. state["no_reply_from"] = turn_author.get("id") if NO_REPLY_MARKER in str(user_message or "") else None
  80. elif state is not None and is_machinery_display_kind(display_kind):
  81. if state["sent"] > state["hops"]:
  82. state["hops"] = state["sent"] = state["sent"] + 1
  83. state["no_reply_from"] = None
  84. elif state is not None:
  85. del _CHAINS[key] # a person spoke: a new chain starts with their message
  86. return
  87. if state is not None:
  88. state["updated"] = now
  89. @dataclass
  90. class Admission:
  91. """One ``message_agent`` call's verdict. ``refusal`` refuses the whole call; ``refused`` maps a
  92. recipient key to its own refusal; ``notify_only`` holds the keys whose message is a reply that
  93. needs no answer. ``release`` hands back what a recipient that was definitely not sent reserved."""
  94. refusal: Optional[str] = None
  95. hop: int = 0
  96. refused: dict = field(default_factory=dict)
  97. notify_only: set = field(default_factory=set)
  98. key: str = ""
  99. asks: dict = field(default_factory=dict)
  100. prior_sent: int = 0
  101. def envelope(self) -> dict:
  102. # Hop 1 is what a receiver assumes for an envelope without the field, so it is left out.
  103. return {"hops": self.hop} if self.hop > 1 else {}
  104. def release(self, recipient: str) -> None:
  105. """Nothing reached ``recipient`` (a definite no-send): forget its ask, and the call's hop once
  106. no recipient of the call went out, so a retry is neither a duplicate nor another hop."""
  107. with _LOCK:
  108. ask = self.asks.pop(recipient, None)
  109. state = _CHAINS.get(self.key)
  110. if ask is None or state is None:
  111. return
  112. state["asks"].discard(ask)
  113. if not self.asks and state["sent"] == self.hop:
  114. state["sent"] = self.prior_sent
  115. def admit_send(agent: Any, recipients: list[str], body: str) -> Admission:
  116. """Check one ``message_agent`` call to ``recipients`` (resolved identities, see the module doc).
  117. Admitted recipients reserve their ask and the call's hop until ``Admission.release``."""
  118. settings = _settings()
  119. if not settings.enabled:
  120. return Admission()
  121. author = getattr(agent, "_turn_author", None) or {}
  122. author_id = str(author.get("id") or "") if author.get("is_bot") else ""
  123. digest = hashlib.sha256(" ".join(str(body).split()).encode()).hexdigest()
  124. with _LOCK:
  125. key = _bound_key(agent)
  126. state = _CHAINS.setdefault(key, _new_state(time.monotonic()))
  127. bot_turn = state["hops"] > 0
  128. hop = state["sent"] + 1 if bot_turn else 1
  129. if hop > settings.max_hops:
  130. return Admission(refusal=(
  131. f"This bot-to-bot exchange already reached its limit of {settings.max_hops} messages "
  132. "(gateway.bot_loop_guard.max_hops), so nothing was sent. Do not retry; finish your turn "
  133. "and tell your user where it stands."))
  134. admission = Admission(hop=hop, key=key, prior_sent=state["sent"])
  135. for recipient in recipients:
  136. ask = (recipient, digest)
  137. replying = bool(author_id) and recipient == author_id
  138. if replying and state["no_reply_from"] == author_id:
  139. admission.refused[recipient] = (
  140. "That bot sent you a reply that needs no answer, so this exchange is over. Do not "
  141. "message them again in this turn; tell your user what you learned instead.")
  142. elif bot_turn and ask in state["asks"]:
  143. admission.refused[recipient] = (
  144. "You already sent this exact message to that bot in this exchange, so it was not "
  145. "sent again. Wait for their answer or say something new.")
  146. else:
  147. state["asks"].add(ask)
  148. admission.asks[recipient] = ask
  149. if replying and not settings.bot_replies_expect_reply:
  150. admission.notify_only.add(recipient)
  151. if admission.asks:
  152. state["sent"] = max(state["sent"], hop)
  153. state["updated"] = time.monotonic()
  154. return admission